Code Samples

 Prerequisite: The Authentication Web service must be installed. For more information, see Security and Authentication.  

AddNewLeadRequest

This method is responsible for initializing a new lead request.

Precondition

Must reference a valid Leads Web service “Admissions”.

Postcondition – Success

A request object is created successfully.

Code Example

// Initialize Request and parameters
Admissions.AddNewLeadRequest request = new Admissions.AddNewLeadRequest();
request.IgnoreDuplicates = false; *
request.TokenId = _tokenId; //**
request.UseValidationTemplate = true; //***
request.ValidationTemplateId = 1; //****
* If this is set to “true”, all leads will be inserted without going through lead validation. The recommended setting here is “false”
**   To get the _tokenId, please see the Authentication Developer’s Guide 
*** Set to true if you want to use a validation template from SyQuickLeadTemplate
**** To obtain a valid Id from database, use the GetList Web service.

LeadInMsg

This method can instantiate one or many lead objects.

Precondition

Must reference a valid Leads Web service “Admissions”.

Postcondition – Success

Lead object(s) created successfully.

Code Example

// Create a new lead
Admissions.LeadInMsg[] leads = new Admissions.LeadInMsg[1];
Admissions.LeadInMsg lead = new Admissions.LeadInMsg();
lead.CorrelationId = 1;
lead.VerifiedLead = true; *
// Populate required fields //**
lead.FirstName = “FirstName”;
lead.LastName = “LastName”;
lead.CampusId = SyCampusId; //***
. . . [Populate any other fields]. . . . //****
leads[0] = lead;
* Possible settings and outcomes for “VerifiedLead” message property 
inMsg.VerifiedLead = false; 
Then: Lead will always go into electronic leads holding table " AmElectronicLeads"
If you set:
request.IgnoreDuplicates = true; 
inMsg.VerifiedLead = true; 
Then: Lead will always go Student table " SyStudent" and bypass any dup processing.
If you set (normal configuration):
request.IgnoreDuplicates = false; 
inMsg.VerifiedLead = true; 
**    Fields required are FirstName, LastName, Lead Date, CampusId, SchoolStatusId, and AdmissionsOfficerId. All other fields are optional unless specified in QuickLeadTemplate and request.UseValidationTemplate = true.
***   To obtain a valid Id from database, use the GetList Web service.
****  For a list of all the LeadMsg fields, see Message Fields.

SSN Validation

The Social Security Number (SSN) is validated for the input message of the API request using a regular expression at runtime based on the prerequisite that the SyCountry.SSNMask is in a string containing ‘#’ and ‘–‘ characters. If there is no SSNMask for the student Country or student Country is not populated on SyStudent, then the API expects the SSN to be in USA format, that is, ###-##-####.

Pseudo Code:

If (Student.SyCounty is NULL OR  Student.Sycountry.SSNMask is NULL / Blank)
{
Validate input.SSN against USA format i.e., ###-##-#####.
}
Else // compare input SSN and SyCountry.SSNMask
{
If (input.SSN.Length not equals to SyCountry.SSNMask.Length)
Throw validation with expected format.
If(Input.SSN.Contains(‘-‘) && SyCountry.SSNMask.Contains(‘-’) is false ) //and vice versa
Throw validation for improper format.
}
Else
Pass the validation.

For more information, see Error Types.

LeadsWebService

This method is used to instantiate the Web service.

Precondition

Must reference a valid Leads Web service “Admissions”.

Postcondition – Success

Web service object created successfully

Code Example

// Create new Lead Web service and assign bind to lead object
Admissions.LeadsWebService service = new Admissions.LeadsWebService();
string url = “http://localhost/cmc.soa.Webservices.admissions/LeadsWebService.asmx";//*
service.Url = url;
request.Leads = leads;
* Make sure the URL matches your Web service location.

AddNewLeadResponse

The AddNewLead Service consumer will send a request in the proper format and with the proper parameters. The service will process the request and return each lead included in the request message with the new generated Id and a transaction result.

Preconditions

  • The request provided is valid.
  • The Leads Web service is configured correctly.
  • Database connection strings are valid.
  • Service consumer authenticates and is authorized to use the service.
  • Must reference a valid Leads Web service “Admissions”.

Postcondition – Success

If the service is able to parse the parameters and execute the request successfully, the service will return one or more leads with their matching record Ids to the client.

Postconditions – Failure

There are several possible causes for failure:

  • Invalid Parameters: If the parameters specified do not match reference values in the current database, the service will return an error in the response message stating the invalid field name.

  • Missing Parameters: If the required parameters are missing, the service will return an error in the transaction result for the message stating the missing field name.

  • Invalid Service Configuration: If there is an invalid configuration for the Web service, the client will receive a generic internal exception message.

Code Example

//Send the request through the Web service and get response
Admissions.AddNewLeadResponse response = service.AddNewLead(request);

Duplicate Lead and Inquiry Processing in the API vs. Anthology Student

The Leads API and Anthology Student have different functionality for processing duplicate leads and inquiries.

  • The Leads API creates a new inquiry based on the Campus Locations >Track Multiple Lead Inquiries configuration. All fields of this inquiry record will be populated based on selected values of a duplicate record. All these fields (Lead Type, Lead Date, Lead Source, Program and Interest) also get updated on the existing Student Master to match the current inquiry record regardless of the duplicate processing criteria set in Campus Locations > Duplicate Lead Process Configuration. Duplicate processing criteria are evaluated only if the new inquiry record does not get created and all the fields on the current inquiry and Student Master are overridden according to the configured criteria.

  • Anthology Student, on other hand, works little differently than the Leads API. A new inquiry record is created based on the Campus Locations >Track Multiple Lead Inquiries configuration. All the fields on the new inquiry that is being created and the existing Student Master get overridden only if the Inquiry check box on Campus Locations > Duplicate Lead Process Configuration is selected to be overridden, not because a new inquiry record gets created.

Duplicate Lead Validation, Configuration, and Interpreting the Response

Leads will go through duplicate check based on Database and API configuration. There are three different cases for lead processing based on this:

Case 1

If a lead is being inserted for the first time and NO DUPLICATES ARE FOUND, a record is inserted into (SyStudent) table, and any activities associated with new student entries are triggered. The API will return a Status of "OK" and an OutMsg along with:

<LeadId>4959073</LeadId> //SyStudentId Assigned

Case 2

If 1 DUPLICATE IS FOUND,  there is a configuration option introduced in build#8006 which controls how duplicates are processed (in case that 1 duplicate is found)

CQ#: 55261 - Severity: 1

Configuration Change: The following new key has been added to the <appSettings> section of the web.config now defaults to the following value:

<add key="NewLeadSingleDuplicateHandling" value="E" />

(Valid options are “E” or “I”)

  • E – Goes to Electronic Leads table
  • I – Adds an Inquiry (current logic)

Reason for change: The other configuration for duplicate processing (“I”) allows leads to be overwritten too easily. The default Anthology Student configuration for duplicate checking “Setup > Campus Locations > Select Campus > Allow > Duplicate Lead Process Configuration > Criteria" sets the duplicate lead criteria to “FirstName and LastName OR Email OR Phone”. This means if “John Smith” comes in as a lead and another “John Smith” comes as another lead, they will over-write each other. The configuration setting of “I” can still be used, but is only recommended for schools with stringent duplicate checking criteria.

Case 3

If MULTIPLE DUPLICATES ARE FOUND,  the lead will always be processed as an electronic lead (AmElectronicLeads) and the API will return the following: 

<LeadId>202</LeadId>  //Processed as Electronic Lead
<VerifiedLead>false</VerifiedLead>

Custom Validation for Postal Codes

In Anthology Student 17.1 and later, the logic that validates postal codes is changed as follows:

  • The validation code is removed from the soa.businessprocess.master.config file located in the following path: \campuslink\cmc.campuslink.soa\common\configuration\cmc.campuslink.soa.businessprocess.master.config

    <!--<field name="PostalCode" type="System.String" operator="ZIP" />-->

  • The PostalCode format is added in the <appSettings> section of the web.config file located in the following path: \campuslink\webservices\cmc.campuslink.webservices\web.config.

    To validate the postal codes associated with a student/lead, the database entry of SyCountry.Code of the supplied Country Code or ID is compared to the value after <add key="CountryCode_".

Users need to edit the web.config file to provide their Country Code after the "_" (underscore) in the key and their desired format for the API to perform the validations.

  • If the Country Code = "CAN" and the entry "<add key="CountryCode_CAN">, the postal code is validated as a Canadian Code [e.g., A2H 4Z5] OR any other Country Code value to its supplied format (see below for examples).

  • If no Country Code is supplied, all postal codes are validated as "US" or "USA", meaning the #####-#### format.

The SkipSemanticValidation flag in the in-message is still used and is set to "False" by default.

  • If SkipSemanticValidation is set "True", postal code validations are ignored.

  • If SkipSemanticValidations is "False", all postal codes are validated against the provided SyCountryID or SyCountryCode.

  • If no Country Code or ID is provided, the default USA format is used, validating the #####-#### or ##### format value.

Users can add entries into the web.config that will allow them to validate postal codes of any other countries that they do business with and in.

Legend:

* = letter
# = number
? = letter or number

Example entries to the web.config are:

<add key="CountryCode_USA" value="#####-####, #####" /> // 33411-1234, 33431
<add key="CountryCode_CANADA" value="*#* #*#" /> // A2H 4Z5
<add key="CountryCode_KEN" value="# ####" /> // 8 1234
<add key="CountryCode_ZIM" value="*?####" /> //A21212 or AB1134
<add key="CountryCode_IN" value="######" /> //457891
<add key="CountryCode_UGL" value="*** ###, ##**??" /> //ABC 123, 55AB1B

For more information, see https://en.wikipedia.org/wiki/List_of_postal_codes

After editing and saving the web.config file, be sure to reset IIS.

Associate Vendors with Lead Sources

A user can associate a lead source with multiple vendors when adding a new lead.

LeadsWebService: Added array of LeadVerndorIds to the message.

Validations for HighSchoolId, HighSchoolGradDate, and HighSchoolStudentLevel

By default, the required state of the fields HighSchoolId, HighSchoolGradDate (GraduationDate), and HighSchoolStudentLevel (amGradeLevelId) is based upon their SyDictionary settings (see Anthology Student > Setup > Data Dictionary).

You can change the validation configuration by editing the Cmc.CampusLink.Soa.BusinessProcess.Master.config file.

To set the validation configuration for these fields:

  1. Navigate to the root where the Leads API is installed (i.e., c:\inetpub\wwwroot\cmc.campuslink.webservices\<<Cmc.CampusLink.Soa.BusinessProcess.Master.config>>)

  2. Scroll down to AddNewLeadInMsgValidation and change the validation necessary to use any regular expression rather than the standard validation.

  3. Find or add a line for any of the fields above, e.g., HighSchoolID:

    <field name="HighSchoolId" type="System.Int32" operator="IN" dbobjectname="HighSchool" dbmethodname="ExistInDB" required="true" /> (The red text was added to make the field a required field.)