NEWSTAR Sales. Web Lead Guide. April 2009 Constellation HomeBuilder Systems, Inc. All right reserved

Transcription

1 NEWSTAR Sales April 2009 Constellation HomeBuilder Systems, Inc. All right reserved

2 Product and Company Information Product and Company Information The information in this document is confidential proprietary information belonging solely to Constellation HomeBuilder Systems, Inc., a wholly owned subsidiary of Constellation Software, Inc. This document is supplied under a license and may not be reproduced, published, or disclosed without prior written authorization. Constellation licenses its program products (software) to the customer in accordance with the terms and conditions of the NEWSTAR Software License Agreement. No title or ownership of the NEWSTAR software is transferred. Any use of the software beyond the terms of the aforesaid license, without the prior written authorization of Constellation, is prohibited. The names of companies, products, people, characters and/or data mentioned in screens, reports, and other data examples are fictitious and are in no way intended to represent any real individual, company, product or event, unless otherwise noted. Any rights not expressly granted herein are reserved. Trademark and Patent Information Other product and company names mentioned herein might be the trademarks of their respective owners. Disclaimer of Warranties and Limitation of Liabilities The staff at Constellation has taken due care in preparing this information; however, nothing contained herein modifies or alters in any way the standard terms and conditions of the NEWSTAR License Agreement by which the product was acquired. Nor does it increase in any way Constellation s liability to the customer. In no event shall Constellation or its affiliates be liable for incidental or consequential damages in connection with or arising from the use of the product, the accompanying documentation, or any related materials. Printed December 7, 2011 i

3 Contacting Support and Services Contacting Support and Services Support for the NEWSTAR software is available at Constellation s Markham office. Constellation HomeBuilder Systems, Inc. 75 Frontenac Drive, West Wing Markham, ON. Canada L3R 6H2 Main Office Telephone or toll-free at Fax Web 0Hwww.constellationhb.com Help Desk Help Desk assists with software operations. Telephone or toll-free at Fax Web 1Hwww.constellationhb.com [email protected] Hours You can reach Help Desk Monday through Thursday 8.00 a.m. to 8.00 p.m. (Eastern Standard Time); Friday 8.00 a.m. to 5.00 p.m., excluding Canadian holidays. Professional Services Contact your company s Professional Services Consultant for assistance with software implementation, training, consulting, and data building. Telephone or toll-free at Fax Web 2Hwww.constellationhb.com ii

4 Table of Contents Table of Contents Product and Company Information... i Trademark and Patent Information... i Disclaimer of Warranties and Limitation of Liabilities... i Contacting Support and Services... ii Introduction... 5 Requirement... 5 Add-On... 5 Homebuyer Prospect - Web Integration... 6 Incoming Prospect data from Website... 6 Required Fields... 7 Optional Fields... 7 Troubleshooting using NEWSTAR Sales... 8 To Do Plans... 8 Update Methods... 9 Buyer Selection... 9 R/E Agent R/E Agencies Integrated s Modifying the Templates Installation Troubleshooting The Code Appendix A: Sample Code Appendix B: Web.Config Additions Appendix C: Error Messages Appendix D: Data Fields iii

5 Introduction Introduction Requirement To run this application, NEWSTAR Sales must be on version or higher. Add-On NEWSTAR Sales has developed an Add-On that imports Prospect data from a thirdparty Website to NEWSTAR Sales via Web Service. The following new Add-On functionalities have been developed: Web service specifications to client (Web service accepting inbound data from the Website) are provided. Incoming Sales Office ID with existing NEWSTAR Sales Sale Office ID is compared. Incoming User ID with existing NEWSTAR Sales User ID is compared. Existing (Web Lead) box where incoming prospect data is from Website is set. Categorized user-friendly messages with each failed transactions have been created. All NEWSTAR Sales/Prospect fields and command buttons are enabled. Please see the following pages and appendices for more information. 5

6 HomeBuyer Homebuyer Prospect - Web Integration The functionalities are detailed in the following pages: Web Lead One Web service will be used per DB for each Website. Generated error messages are categorized and user-friendly. Please see Appendix C. Web Service resides on client internal network. Web Service security settings, configurations, configuration Files, setup are maintained by client.+ Incoming Prospect data from Website You can map any of the fields you see below to your website. Once the Web site is mapped to the NEWSTAR Sales Sales Office, the WebLeads application will create the Prospect record directly into NEWSTAR Sales. Prospect Screen 6

7 HomeBuyer Required Fields The fields below must be included in your WebLeads mapping between to your website the NEWSTAR Sales database. Incoming Sales Office ID o Where Sales Office ID exists in NEWSTAR Sales, then the transaction continues. o Where Sales Office ID does not exist in NEWSTAR Sales, then Sales Office name from Web Config. File is used and the transaction continues. o Where Sales Office name is not found, a message displays and the transaction discontinues. Prospect First and Last name o These fields should be made mandatory on your website form and error out when the customer selects Submit as this will cause the WebLead transfer to error on the import to NEWSTAR Sales. User (that this prospect will be assigned to) o Where User ID exists in NEWSTAR Sales, the transaction continues. o Where User ID does not exist in NEWSTAR Sales and then User Login ID from Web Config. file is used and the transaction continues. o Where not found, a message displays and the transaction discontinues. Optional Fields The remaining fields found on the Prospect window are optional and can be linked if desired. Where you are linking the additional fields to your website please be cautious of required formats for NEWSTAR Sales Prospect Address o Will transfer as entered by the customer o Where left blank will transfer as blank. State and Country o Where State and Country codes match in NEWSTAR Sale, update and continue transaction. o Where State and Country does not exist or match exactly in NEWSTAR Sales - N/A will be transferred. Note: N/A must exist in the City and Country table within NEWSTAR Sales. N/A is included on these tables by default during system installation. If you are getting error with N/A check your database as a user may have revised or deleted it. Dates To confirm a list of your valid Countries and States go to: NEWSTAR Sales > System Masters > Counties and States and Add/Edit/Delete as required. 7

8 HomeBuyer o Ensure that dates formats match on both the website and NEWSTAR Sales (MM/DD/YYYY) Phone Numbers o Ensure phone numbers match a format of ###-###-#### Troubleshooting using NEWSTAR Sales o If you were to try to enter the data being captured on your website manually by rekeying it in NEWSTAR Sales directly and you get an error message on any of the fields, this will stop WebLeads from passing the data. Go to NEWSTAR Sales, Select Prospect Look up (Address Book section on the left) Select New Prospect on the Prospect Look up window Complete the desired fields Select Save at the bottom of the window o o If the above steps can be completed without errors, there is a problem with the mapping from the website. If the above steps cannot be completed without errors, the required system checking and/or required fields need to be added at your website level. To Do Plans When a Prospect is created in NEWSTAR Sales via the WebLeads application the system will attach the ToDo Plan marked as Default for the specific Sales Office. Refer to NEWSTAR Sales > System Administration > Select your desired Sales Office at the top, the select the To Do Plans button. ToDo Plans o If incoming prospect To Do Plan has task assigned to it in NSS Sales Office, then update prospect/to Do with the task o If no ToDo Plan is assigned to the incoming Prospect then assign NSS Sales Office default ToDo plan. o If no ToDo Plan is assigned to the incoming Prospect and no NSS Sales Office default ToDo plan then leave blank o Where Prospect To Do plan and tasks exist in NSS for web lead prospect, and web lead user changes the prospect Sales Office: If new sales office does not have the existing to do plan and task, send error message If new sales office to do plan and tasks are exactly the same as old sales office then update the application with new sales office to do plan and tasks If to do plan exist in new Sales Office with different tasks plan, then update NSS with new sales office to do plan tasks by keeping old completed and manually entered tasks 8

9 HomeBuyer Update Methods Add o Where Sales Office ID and User ID condition are met, the Prospect transaction continues. For incoming Prospect data (Web Lead) field is set to true. Check for duplicate prospect record. If found, an error notification will display. If not found, prospect update continues: All NEWSTAR Sales/Prospect fields are enabled. Update incoming Prospect First name, Last name mandatory fields. Set First Visit with incoming value, if missing, use today s date. Add NEWSTAR Sales prospect record with incoming optional field values (if any) like Title, Salutation, Co- Buyer, Home/Work phone numbers, Cell number, Fax Number, Date of Birth, S.S.N Contacts, Home/work , R/E Agency, R/E Agent, ToDo values. Update Find Prospect o Update existing Prospect first, last name and address with new incoming value (if any). o Update Existing NEWSTAR Sales prospect record with incoming optional field values (if any) like Title, Salutation, Co-Buyer, Home/Work phone numbers, Cell number, Fax Number, Date of Birth, S.S.N Contacts, Home/work , R/E Agency, R/E Agent, ToDo values. Delete Find existing Prospect o Where Prospect is deleted, NEWSTAR Sales Prospect is marked as archived and Co-Buyers, Contact, Finance data from NEWSTAR Sales removed. o Where optional field values are deleted, remove (delete) corresponding field values in NSS. Buyer Selection For Incoming prospects from Website, where Prospect State and Country values are set to N/A users are not allowed to add selection and an error message will display. 9

10 HomeBuyer R/E Agencies For incoming Real Estate Agencies which contains Real Estate Agent with no Prospect Create record on NEWSTAR Sales/System Admin R/E Agencies o Required Field - Name of Real Estate Agency. Additional fields o State code must be blank or valid in state table. o Address, City, Zip, Contact, , Phone, Fax, R/E Agent. R/E Agent For incoming Real Estate agents which are not assigned to any prospect: Create record on NEWSTAR Sales System Admin/Realtors o Required Fields R/E Agency ID must exist in NEWSTAR Sales R/E Agencies. First And Last name. Additional fields o Title must be one of the following defined values: Mr., Mrs., Ms., Miss., Dr., Prof., Rev. o State code must be blank or valid in state table. o Address, City, Zip, , Business Phone, Home Phone, Fax, Pager, Cell, SSN. 10

11 HomeBuyer Integrated s There are two default layouts that are delivered with WebLeads to the location outlined below. You can create and add additional s if desired. Be sure to activate your intended s in the Web.Config file (refer to Appendix B) AlertFormat this is an internal notifying of the prospect on the website Format this can be set as an auto response to the prospect. C:\inetpub\wwwroot\nssws Data Fields available for merge to templates Refer to Appendix D: Data Fields, found at the bottom of this document. Be sure to add ~~ in the front and back of each field. Example: ~~FIRSTNAME~~ 11

12 HomeBuyer Modifying the Templates 1. Open the desired file using Notepad 2. Insert or remove mail merge fields 3. Insert or delete the desired text 12

13 HomeBuyer For sample code, please see Appendix A. For Web.Config Additions, please see Appendix B. For errors messages, please see Appendix C. For data fields, please see Appendix D. 13

14 Installation Installation Please check that you have the requirements before you start installation. Requirements: IIS 6.0 or higher ASP 2.0.Net Framework 3.5 Installation steps: 1. Verify that you have the following files in the package. setup.exe NSSWS.msi 2. Run setup.exe 3. If you don t have.net 3.5, the setup will automatically download and install it for you. If you don t see the following message, then it means you already have it installed and the setup will move on to the next step. 14

15 Installation 4. The installation window will open. Simply click Next to continue. 15

16 Installation 5. If you have multiple sites running from the same machine then make sure you select the correct website. If you don t have multiple sites, then simply choose the Default Website. Virtual Directory must be NSSWS. If you have multiple application pools or running different ASP versions on the same site, then you must create or choose an appropriate application pool. Unfortunately IIS cannot run multiple versions of ASP in the same application pool. If you only have ASP 2.0 running on this website or you will not be running anything other than this service on the website then you can select DefaultAppPool. Click Next to continue. 16

17 Installation 6. Click Next to continue. 7. The setup will proceed with the installation and show you confirmation that it has completed successfully. 17

18 Installation 8. Using Windows Explorer browser to the website path and then go to NSSWS directory. Find web.config file and open it using Notepad to edit. 9. Modify the following lines: a. <add key="sendprospectalerttouser" value="[yes NO]"/> This requires that the user in NSS has an address. b. <add key="chsaccountid" value="[chs ID ASSIGNED DURING IMPLEMENTATION]"/> 18

19 Installation 10. The installation is done at this point. We recommend you would test the installation before deploying it to your user base to ensure everything has been set up correctly. Troubleshooting The Code The database connection and configuration can be tested by browsing to Standard connections string is similar to below: <add key="nssconnection" value="data Source= ;Initial Catalog=SPLive;User Id=WSS;Password=NSSWS;"/> Receiving error 40 with description Unable to establish a connection to SQL Server then it is most likely one of the following: a. Check this by pinging or using telnet to connect to port 1433, telnet <servername> If it doesn t connect then that means the server is not listening on the port. b. Firewall The most common issue, on Vista and Windows server 2008 you must enable port 1433 from the windows firewall c. TCP network is not enabled i. SQL Server 2000 with the latest service packs and updates 1. Check Server Network utility and make sure TCP is enabled and it is using port Check the SQL Server log to see what services are started. 3. Make sure SQL Server SP4 is installed. 4. Go to Client Network utility and make sure TCP is the first method of connection and it is using port ii. SQL Server 2005/ Go to SQL Configuration tools and make sure TCP is active 2. Make sure the TCP is using 1433 port 19

20 Appendix A: Sample Code Appendix A: Sample Code C# protected void Button1_Click(object sender, EventArgs e) { //Existing form processing goes here //construct POST string post = "FirstName=" + Server.UrlEncode(TextBox1.Text) + "&LastName=" + Server.UrlEncode(TextBox2.Text) + "&HomePhone=" + Server.UrlEncode(TextBox3.Text) + "&Home =" + Server.UrlEncode(TextBox4.Text) + "&Notes=" + Server.UrlEncode(TextBox5.Text) //Token value in POST must match token in Web.Config + "&Token=" + Server.UrlEncode("NSSTOKEN") + "&Entity=" + Server.UrlEncode("Prospect") + "&Transaction=" + Server.UrlEncode("Add"); //set POST url - replace with NSS webservice URL string url = " //create webrequest object and set headers for POST System.Net.HttpWebRequest request = (System.Net.HttpWebRequest)System.Net.WebRequest.Create(url); request.method = "POST"; request.contenttype = "application/x-www-form-urlencoded"; request.contentlength = post.length; request.keepalive = false; //create streamwriter object and send data System.IO.StreamWriter sw = new System.IO.StreamWriter(request.GetRequestStream()); sw.write(post); sw.close(); } PHP <?php if ($_SERVER['REQUEST_METHOD'] == "POST") { //Existing form processing goes here //START NSS Lead Submission $strpost = ""; //create string with POST data $strpost = "FirstName=". urlencode($_post['first_name']). "&LastName=". urlencode($_post['last_name']). "&Home =". urlencode($_post['home_ ']). "&HomePhone=". urlencode($_post['home_phone']). "&Notes=". urlencode($_post['notes']) 20

21 Appendix A: Sample Code //Token value in POST must match token in Web.Config. "&Token=". urlencode('nsstoken');. "&Entity=". urlencode('prospect');. "&Transaction=". urlencode('add'); //put POST header and data into array $context_options = array ( 'http' => array ( 'method' => 'POST', 'header'=> "Content-type: application/x-www-formurlencoded\r\n" "Content-Length: ". strlen($strpost). "\r\n", 'content' => $strpost ) ); //set POST url - replace with NSS webservice URL $ctx $url = " //allow_url_fopen must be set to true in your php.ini file to use fopen with a 'r', false, $ctx); }?> 21

22 Appendix B: Web.Config Additons Appendix B: Web.Config Additions <appsettings> <add key="authtoken" value="nsstoken"/> <add key="nssconnection" value="data Source=myServerAddress;Initial Catalog=myDataBase;User Id=myUsername;Password=myPassword;"/> <add key="userloginid" value="[default USER TO RECEIVE PROSPECTS]"/> <add key="salesofficename" value="[sales OFFICE NAME]"/> <add key="sendprospectalert" value="[yes NO]"/> <add key="sendprospectalertsmtp" value="[smtp SERVER]"/> <add key="sendprospectalertsmtpport" value="[smtp PORT NUMER]"/> <add key="sendprospectalertsmtpusessl" value="[yes NO]"/> <add key="sendprospectalertsmtpuseauth" value="[yes NO]"/> <add key="sendprospectalertsmtpauthname" value="[auth NAME]"/> <add key="sendprospectalertsmtpauthpass" value="[auth PASSWORD]"/> <add key="sendprospectalertsmtpauthdomain" value="[auth DOMAIN NAME]"/> <add key="sendprospectalertto" value="[smtp ADDRESS]"/> <add key="sendprospectalertcc" value="[smtp ADDRESS]"/> <add key="sendprospectalertbcc" value="[smtp ADDRESS]"/> <add key="sendprospectalertfrom" value="[smtp ADDRESS]"/> <add key="sendprospectalertsubjectprefix" value="prospect Alert: "/> <add key="sendprospectalertformatfile" value="alertformat.nss"/> </appsettings> 22

23 Appendix C: Error Messages Appendix C: Error Messages 401 Invalid Transaction 401 Invalid Entity 201 Error accessing NSS DB 301 NSSConection info is missing in config file 401 Missing or invalid First Name or Last Name 501 Invalid BirthDate format 401 Invalid CRM value 401 Invalid WebLead value 501 Invalid FirstVisitDate format 601 Inserting Prospect will create duplicate prospect 101 Error inserting ProspectVisit record 401 Invalid CobuyerShowInContract value 401 Invalid CobuyerAddToMailing value 401 Invalid CobuyerState 501 Invalid CobuyerBirthDate 101 Cobuyer Record not updated 401 Missing ProspectID 401 Invalid ProspectID 401 Missing or invalid First Name or Last Name 701 Adding REAgent will create duplicate 401 Missing REAgentID 401 Invalid REAgentID 401 Missing REAgencyID 101 REAgencyID not found in DB 701 Updating REAgent will create duplicate 401 Missing REAgency name 401 Invalid REAgencyID 401 Invalid UserID 101 UserID not found in DB 201 Error retrieving User 101 UserID is missing and UserLoginID from sysconfig not found in DB 201 Error reading UserLoginID from DB 401 Invalid SalesOfficeID 101 Sales Office not found in DB 201 Error retrieving Sales Office 101 SalesOfficeID is missing and SalesOfficeName from sysconfig not found in DB 201 Error reading SalesOfficeID from DB 401 Missing SalesOfficeID 101 State <State> And Country <Country> not found in DB 201 Error reading StateID from DB 401 Invalid REAgencyID 23

24 Appendix C: Error Messages 101 REAgencyID not found in DB 201 Error reading REAgencyID from DB 401 Invalid REAgentID 101 REAgentID not found in DB 201 Error reading REAgentID from DB 401 Invalid SOToDoPlanID 101 SOToDoPlanID not found in DB 201 Error reading SOToDoPlanID from DB 701 Error checking duplicate prospect 201 Error reading inserted prospect record 201 Error inserting prospect record 101 Cobuyer does not exist in DB 101 Multiple Cobuyer records found 201 Error reading Cobuyer record 201 Error updating Cobuyer record 201 Error updating prospect record 201 Error reading inserted REAgency record Error updating REAgency record 201 Error checking for duplicate REAgents 201 Error reading inserted REAgent record 201 Error inserting REAgent record 201 Error updating REAgent record 401 Invalid REAgencyID 401 Invalid UserID 101 UserID not found in DB 201 Error retrieving User 101 UserID is missing and UserLoginID from sysconfig not found in DB 201 Error reading UserLoginID from DB 401 Invalid SalesOfficeID 101 Sales Office not found in DB 201 Error retrieving Sales Office 24

25 Appendix D: Data Fields Appendix D: Data Fields Prospect Add/Update Transactions Field In Request Field in DB Type Req. Comments/Validation Title Title String(5) No Must be on the list: Mr., Mrs., Ms., Miss, Dr., Prof., Rev. FirstName FirstName String(25) Yes LastName LastName String(25) Yes ProspectID ProspectID Int Only for Update Address1 Address1 String(50) No If Empty then N/A used Address2 Address2 String(50) No City City String(25) No If Empty then N/A used StateCode StateID String(5) No Existing Code in States table. (must be blank or valid) Country Country String(30) No Existing Name in Countries table. State and Country together must identify unique record in States and table. (must be blank or valid). If blank then record in States with the Code= N/A and referencing the record in Countries table with Name= N/A is used. If State record cannot be identified then Error returned. ZipPostal ZipPostal String(15) No Birthdate Birthdate Date string No 01-Mar-2009 [dd-mmm-yyyy] SSN SSN String(15) No Salutation Salutation String(5) No HomePhone HomePhone String(32) No BusinessPhone BusinessPhone String(32) No CellPhone CellPhone String(32) No Fax Fax String(32) No Home Home String(2000) No Work Work String(2000) No REAgentID REAgentID Integer No Existing record ID in REAgents table (must be blank or valid) Weblead Weblead Bit No If not blank then must be 0 or 1 CRM CRM Bit No If not blank then must be 0 or 1 SoToDoPlanID SoToDoPlanID Integer No Existing record in SOToDoPlans table FirstVisitDate ProspectVisits Date No If missing then ToDay used [dd- 25

26 Appendix D: Data Fields record being inserted MMM-yyyy] Record inserted into ProspectViits table with VisitType = First Visit UserID UserID Integer Yes Existing record ID in Users table If UserID is missing then UserLoginID from WebConfig file used SalesOfficeID SalesOfficeID Integer Yes Existing UserID in SalesOffices table If SalesOfficeID is missing then SalesOfficeName from WebConfig is used REAgencies Add/Update Transactions Field In Request Field In DB Type Req. Comments Name Name String(50) Yes REAgencyID REAgencyID Int Only for Update Address1 Address1 String(50) No Address2 Address2 String(50) No City City String(25) No StateCode StateID String(5) No See comments for Prospect fields. Country String(50) No Zip Zip String(15) No Contact Contact String(50) No String(2000) No Phone Phone String(32) No Fax Fax String(32) No Modem Modem String(32) No WebSiteUrl WebSiteUrl String(2000) No MLSNo MLSNo String(20) No Notes Notes String(2000) No SOToDoPlanID SOToDoPlanID Int No See comments for Prospect fields. RE Agents Add/Update Transactions Field In Request Field in DB Type Req. Comments REAgencyID REAgencyID Integer Yes ID of existing record in REAgencies REAgentID REAgentID Integer Yes Only for Update. Title Title String(5) No Must be on the list: Mr., Mrs., Ms., Miss, Dr., Prof., Rev. Salutation Salutation 26

27 Appendix D: Data Fields FirstName FirstName String(25) Yes LastName LastName String(25) Yes Address1 Address1 String(50) No Address2 Address2 String(50) No City City String(25) No StateCode StateCode String(5) No See comments for Prospect fields. Country String(50) No ZipPostal ZipPostal String(15) No String(2000) No BusinessPhone WorkPhone String(32) No HomePhone HomePhone String(32) No Fax Fax String(32) No Pager Pager String(32) No CellPhone Cell String(32) No WebSiteUrl WebSiteUrl String(2000) No SSN SSN String(15) No Notes Notes String(2000) No SOToDoPlanID SOToDoPlanID Integer No Must be valid SOToDoPlanID 27