UGC Core API

Follow

The Core UGC API is used to save, get, list, and delete UGC records. It is available as a JS API and a .NET API.

New: Looking for instructions on how to use the UGC JS SDK with npm? Go to GitHub for the latest build using npm.

API Methods

GetRecord Method

The GetRecord call returns the entire record defined by the recordID. This call is used to retrieve records in the Website Users tables and the User Generated Content tables. Note that GetRecord will only return records that are published when using a standard authentication process. If an admin API key and password are used GetRecord is able to access any record with the UGC system regardless of state.

Parameters

  • recordID
    • Integer
    • The numeric ID that is assigned to every record in the Agility UGC content store.
    • Corresponds to Record.ID from any record object.

Returns

  • Record

Usage

Use the call to get all of the data for a given record, including the metadata for any File fields and large text fields.  This is best for a “details” page, where you have already retrieved the recordID based on list selection and need to access all of the data for a record.

 

Agility.UGC.API.GetRecord (JS)

//invoke the GetRecord method with a known recordID variable

Agility.UGC.API.GetRecord(recordID, function(data) {	
	
	if (data.ResponseType != Agility.UGC.API.ResponseType.OK) {
		//error occurred
		alert("An error occurred: " + data.Message);			
	} else {
		//data.ResponseData is a "Record" object
		var record = data.ResponseData;
		
		//get the firstname and lastname properties of the record...
		var firstName = record.FirstName;
		var lastName = records.LastName;		
	}
});

 

Agility.UGC.API.GetRecord (.NET)

//invoke the GetRecord method with a known recordID variable
 
using (Agility_UGC_API_WCFClient client = DataServiceUtil.GetUGCClient())
{
   DataServiceAuthorization auth =
     DataServiceUtil.GetDataServiceAuthorization(-1);
                     
   Record record = client.GetRecord(auth, recordID);
 
   if (record != null) 
   {
      //get the firstname and lastname 
      //properties of the record...
      var firstName = records["FirstName"];
      var lastName = records["LastName"];
   }
}


SaveRecord Method

 The SaveRecord call is used to save new or existing records.

Parameters

  • Record
    • The record object to save.  If a new object is being created, only the RecordTypeName and custom fields need to be populated.

Returns

  • recordID
    • The record ID that was saved.

Usage

This is the universal method for saving new and existing records.  If you have a new record, you can save it using the code example below.  If you have an existing record, such as one retrieved from a GetRecord call, you can simply change the fields in the Record object as necessary and save it using this call.  Any fields that have not been changed will not be affected.

Note: The integer value returned from using the UGC “SaveRecord” method is the primary key of that inserted record.

 

Agility.UGC.API.SaveRecord (JS)

//construct a new record object
//the RecordTypeName is required, specified in Agility
//the FirstName and LastName fields are custom fields
var record = {
	RecordTypeName: "Profile", 
	EmailAddress: "John@Doe.com",
	FirstName: "John"
}

//invoke the SaveRecord method with a known recordID variable
Agility.UGC.API.SaveRecord(record, function(data) {	
	
	if (data.ResponseType != Agility.UGC.API.ResponseType.OK) {
		//error occurred
		alert("An error occurred: " + data.Message);			
	} else {
		//data.ResponseData is the recordID of the saved record.
		var recordID = data.ResponseData;		
	}
});

//if you have a custom cache key that you wanted to invalidate the cache for, you would use the following:
var cacheKey = "MyCacheKey";  //normally this key will be a computed value, possibly container an id from another record.

Agility.UGC.API.SaveRecord(record, function(data) {	
	
	if (data.ResponseType != Agility.UGC.API.ResponseType.OK) {
		//error occurred
		alert("An error occurred: " + data.Message);			
	} else {
		//data.ResponseData is the recordID of the saved record.
		var recordID = data.ResponseData;		
	}
}, cacheKey);

 

Agility.UGC.API.SaveRecord (.NET)

//construct a new record object
//the RecordTypeName is required, specified in Agility
//the FirstName and LastName fields are custom fields
Record userRecord = new Record();
userRecord.RecordTypeName = "Profile";
userRecord["EmailAddress"] = email;
userRecord["FirstName"] = name;
 
using (Agility_UGC_API_WCFClient client = DataServiceUtil.GetUGCClient())
{
   DataServiceAuthorization auth =
     DataServiceUtil.GetDataServiceAuthorization(-1);
 
   int recordID = client.SaveRecord(auth, record);
 
}
 
 
//if you have a custom cache key that you wanted to invalidate the cache for, you would use the following:
var cacheKey = "MyCacheKey";  //normally this key will be a computed value, possibly container an id from another record.
using (Agility_UGC_API_WCFClient client = DataServiceUtil.GetUGCClient())
{
   DataServiceAuthorization auth =
     DataServiceUtil.GetDataServiceAuthorization(-1);
 
   int recordID = client.SaveRecord(auth, record, cacheKey);
 
}

 

SearchRecords Method

This method is used to retrieve content from the Agility UGC content store. Use this function to retrieve content of all types and user information for your Website Users. SearchRecords allows for paging through a result set of any records within a given User Generated Content Definition or Website User Type.  

Parameters

Parameter  Description 
 Auth (DataServiceAuthorization)

This object can be retrieved from the DataServiceUtil class in the API dll.

 searchArg (RecordSearchArg)

Object of type Agility.UGC.API.SearchArg

PageSize = 20

The page size.  0 will return the max page size, 1000.

RecordOffset = 0

The first record to start returning results from.

SortedField = ""

The field name to sort the results by. This may be any field defined on the User Generated Content definition in the RecordType, or any of the following built-in values: CreatedOn, ModifiedOn.

SortDirection = ""
  • String

  • ASC or DESC.

RecordTypeName = “<User Generated Content Definition Reference Name>” OR “<Website User Type Reference Name>”
  • String

  • The reference name of the User Generated Content Definition or Website User Type as configured in Agility.

 Search = ""
  • The search query

  • Can be in the following format:

  • FieldName1 = ‘StringValue’ &&  (FieldName2 > NumValX ||  FieldName2 < NumValY)

  • This query relies on the use of && (for AND) and || (for OR) and a space before and after each operator ( = ,  < , > ,  LIKE ).   

  • Brackets may be used, but not nested.  

  • To filter using dates, you must provide them in "yyyy-MM-dd" format. For example, "MyDateProperty > '2011-01-31'".

  • SQL inject attempts will return an error.

  • In addition to fields you have added to the record type definition, you may also search using the ID, ModifiedOn, ModeratedOn, AbuseCount, CreatedByRecordID, ModifiedByRecordID, and ModeratedByRecordID fields as criteria.

CacheKey = ""
  • Optional

  • The custom cache key.

  • Using this ensures that any search results that have been accessed using this cache key will be cleared as a group when SaveRecords is called with this cacheKey included as a parameter, or when ClearCache is called with this cacheKey as a parameter.

 

Returns

  • PagedResult object
    • TotalRecords
      • Integer – the total number of records that matched the search
    • List<Record> – Records
      • The current page of data in the result set as an array of record objects
      • See the Introduction section for a description of the Record object

Usage

SearchRecords is used any time data is retrieved from the Agility UGC content store.  For example, listing records, populating dropdown menus, searching for specific content, and any situation where you need to find a record in UGC based on a User Generated Content Definition or Website User Type. Please note that SearchRecords does not return all metadata for File type fields and large text fields.  This additional metadata can be retrieved by the GetRecord() call.

 

Agility.UGC.API.SearchRecords (JS)

//search for records in the "Profiles" Website User Type table
//only return 10 records at a time
//start at the beginning of the results
//find record that have FirstName starting with Joe

var searchArg = new Agility.UGC.API.SearchArg();
searchArg.RecordTypeName = "Profile";
searchArg.PageSize = 10; 
searchArg.RecordOffset= 0; 
searchArg.Search = "FirstName LIKE 'Joe%'";		

//if the data should be cached based on a custom key...
searchArg.CacheKey = "MyCustomCacheKey"; //TODO: calculate this key value, and only use if necessary.

//invoke the SearchRecords method, which is asynchronous, and has a callback
Agility.UGC.API.SearchRecords(searchArg, function(data) {	
	
	if (data.ResponseType != Agility.UGC.API.ResponseType.OK) {
		//error occurred
		alert("An error occurred: " + data.Message);			
	} else {
		//data.ResponseData is a "PagedResult" object 
		//with Records and TotalRecords properties.
		var records = data.ResponseData.Records;
		var totalRecords= data.ResponseData.TotalRecords;
		
		//get the firstname and lastname 
		//properties of the first record...
		var firstName = records[0].FirstName;
		var lastName = records[0].LastName;		
	}
})

 

Agility.UGC.API.SearchRecords (.NET)

//search for records in the "Profiles" Website User Type table
//only return 10 records at a time
//start at the beginning of the results
//find record that have FirstName starting with Joe
 
using (Agility_UGC_API_WCFClient client = DataServiceUtil.GetUGCClient())
{
   DataServiceAuthorization auth =
     DataServiceUtil.GetDataServiceAuthorization(-1);
                     
    //build the search argument
   RecordSearchArg arg = new RecordSearchArg() {
      RecordTypeName = " Profile ",
    Search = "FirstName LIKE 'Joe%'",
      PageSize = 10,
    RecordOffset = 0                    
   };
 
//if the data should be cached based on a custom key...
arg.CacheKey = "MyCustomCacheKey"; //TODO: calculate this key value, and only use if necessary.
 
 
    
   PagedResult result = client.SearchRecords(auth, arg);
 
 
   int count = result.TotalRecords; searchArg.RecordTypeName = "Profile";
   //get the firstname and lastname 
   //properties of the first record...
   var firstName = records[0]["FirstName"];
   var lastName = records[0]["LastName"];
}

 

ClearCache Method

The ClearCache method allows you clear a set of search results from cache based on a specified key. Use this method if you want to clear cache but you are not saving a record.

Agility.UGC.API.ClearCache (JS)

//if the data should be cached based on a custom key...
var cacheKey= "MyCustomCacheKey";
 
//invoke the ClearCache method, which is asynchronous, and has a callback
Agility.UGC.API.ClearCache(cacheKey, function(data) {  
     
    if (data.ResponseType != Agility.UGC.API.ResponseType.OK) {
        //error occurred
        alert("An error occurred: " + data.Message);           
    } else {
        //the cache was cleared successfully...
    }
})

 

Agility.UGC.API.ClearCache (.NET)

using (Agility_UGC_API_WCFClient client = DataServiceUtil.GetUGCClient())
{
     DataServiceAuthorization auth =
     DataServiceUtil.GetDataServiceAuthorization(-1);
     //TODO: generate this key based on realistic parameters.
     string cacheKey = "MyCustomCacheKey"; 
     client.ClearCache(auth, cacheKey);
}

 

Delete Method

Please see Deleting UGC Records using the API for details.

 

0 out of 1 found this helpful

Comments

0 comments

Please sign in to leave a comment.