Kaizen 85 - PHP SDK Part II

Hello everyone! Welcome to another week of Kaizen!

In last week's post, we discussed in detail the configuration and initialization steps for PHP SDK. We will take you through sample codes for Record Operations this week, to help you get started with your SDK journey.

1. Custom Fields, Lookup Fields, Picklist Fields

1.1 Custom Fields

To set/update a value for a custom field during a record create/update, use addKeyValue method. This method takes two arguments - the field API name and the value.

$variable->addKeyValue("your_custom_field_api_name", "custom_field_value");

$record->addKeyValue("Designation", "Manager");

1.2 Picklist Fields

To set/update a value for a default picklist field like 'Lead Source' in Leads module, use addFieldValue method in the following format.

$variable->addFieldValue(ModuleAPIName::FieldName(), new Choice("picklist_value"));

$record->addFieldValue(Contacts::LeadSource(), new Choice("Advertisement"));

Specify your option for the picklist field when you create the Choice class instance. In this example, the LeadsSoure picklist field in Contacts will be updated with the value Advertisement if it is a option for the picklist. If an invalid value is specified, the SDK will throw an UNACCEPTED VALUES ERROR.

For user defined Picklist fields, use the addKeyValue method in the following format.

$variable->addKeyValue("custom_picklist_field_api_name", new Choice("picklist_choice"));

$record->addKeyValue("Pick_List_2", new Choice("Option 1"));

1.3 Lookup Fields

To set/update a value for a default Lookup field during a record create/update, use addFieldValue method in the following format.

$lookupVariable = new Record();

$lookupVariable->addKeyValue("id", "lookup_record_id");

$recordVariable->addFieldValue(LookupModule::FieldName(), $lookupVariable);

$lookup = new Record();
$lookup->addKeyValue("id", "554597402674230");
$record->addFieldValue(Contacts::AccountName(), $lookup);

For custom Lookup fields, use the addKeyValue method in the following format.

$lookupVariable = new Record();

$lookupVariable->addKeyValue("id", "lookup_record_id");

$recordVariable->addKeyValue("Lookup_Field_API_Name", $lookupVariable);

$lookup = new Record();
$lookup->addKeyValue("id", "55459742674230");
$record->addKeyValue("Lookup_1", $lookup);

For Owner Lookup fields, use the addFieldValue method in the following format.

$ownerVariable = new User();

$ownerVariable->setEmail("name@domain.com");

$recordVariable->addKeyValue("Owner_Field_API_Name", $recordVariable);

$recordOwner = new User();
$recordOwner->setEmail("patricia.boyle@zylker.com");
$record->addKeyValue("Owner", $recordOwner);

Sample Code for creating a new record in Contacts module with the above field types.

<?php

use com\zoho\crm\api\HeaderMap;

use com\zoho\crm\api\record\BodyWrapper;

use com\zoho\crm\api\record\RecordOperations;

use com\zoho\crm\api\record\Contacts;

use com\zoho\crm\api\util\Choice;

use com\zoho\crm\api\users\User;

use com\zoho\crm\api\record\Record;

require_once "vendor/autoload.php";

class CreateRecords {

public static function initialize() {

// add initialisation code

// refer to the previous post for details and examples

}

public static function createRecords1(string $moduleAPIName) {

$recordOperations = new RecordOperations();

$bodyWrapper = new BodyWrapper();

$record = new Record();

//standard field

$record->addFieldValue(Contacts::LastName(), "Boyle");

//custom field

$record->addKeyValue("Designation", "Accountant");

// custom picklist field

$record->addKeyValue("Pick_List_2", new Choice("Option 1"));

//custom lookup field

$lookup = new Record();

$lookup->addKeyValue("id", "5545974771087");

$record->addKeyValue("Lookup_1", $lookup);

//Standard picklist field

$record->addFieldValue(Contacts::LeadSource(), new Choice("Advertisement"));

//Standard lookup field

$lookup1 = new Record();

$lookup1->addKeyValue("id", "55459742674230");

$record->addFieldValue(Contacts::AccountName(), $lookup1);

//Owner lookup field

$recordOwner = new User();

$recordOwner->setEmail("pat.boyle@zylker.com");

$record->addKeyValue("Owner", $recordOwner);

$bodyWrapper->setData([$record]);

$trigger = ["approval", "workflow", "blueprint"];

$bodyWrapper->setTrigger($trigger);

$headerInstance = new HeaderMap();

$response = $recordOperations->createRecords($moduleAPIName, $bodyWrapper, $headerInstance);

//Add code to handle the response received in $response.

// For more details, refer here.

}

CreateRecords::initialize();

$moduleAPIName = "Contacts";

CreateRecords::createRecords1($moduleAPIName);

2. Multi-select Lookup Fields, Multi-select Picklist Fields and Multi-user Picklist Fields

2.1 Multi-select Lookup Fields

Use the following format to set or update Multi-select Lookup Fields while creating or updating a record.

$LookupVar1 = new Record();

$LookupVar1->addKeyValue("id", "lookup_record_id1");

$mslookupVariable1 = new Record();

$mslookupVariable1->addKeyValue("Field_API_Name", $LookupVar1);

$LookupVar2 = new Record();

$LookupVar2->addKeyValue("id", "lookup_record_id2");

$mslookupVariable2 = new Record();

$mslookupVariable2->addKeyValue("Field_API_Name", $LookupVar2);

$record->addKeyValue("Field_API_Name", [$mslookupVariable1, $mslookupVariable2]);

2.2 Multi-select Picklist Fields

Use the following format to set or update Multi-select Picklist Fields while creating or updating a record.

$variable->addKeyValue("Picklist_Field_API_Name", [new Choice("Picklist_Value1"), new Choice("Picklist_Value2")]);

2.3 Custom Multi-user Picklist Fields

To set or update a custom Multi-user Picklist Field, use the following format.

$lookupVar1 = new User();

$lookupVar1->addKeyValue("id", "user_id1");

$mulookupVariable1= new User();

$mulookupVariable1->addKeyValue("Field_API_Name", $lookupVar1);

$lookupVar2 = new User();

$lookupVar2->addKeyValue("id", "user_id2");

$mulookupVariable2= new User();

$mulookupVariable2->addKeyValue("Field_API_Name", $lookupVar2);

$record->addKeyValue("Field_API_Name", [$mulookupVariable1, $mulookupVariable2]);

Here is a sample code to create a record in Contacts module with the above field types.

<?php

use com\zoho\crm\api\HeaderMap;

use com\zoho\crm\api\record\BodyWrapper;

use com\zoho\crm\api\record\RecordOperations;

use com\zoho\crm\api\record\Contacts;

use com\zoho\crm\api\util\Choice;

use com\zoho\crm\api\users\User;

use com\zoho\crm\api\record\Record;

require_once "vendor/autoload.php";

class CreateRecords {

public static function initialize() {

// add initialisation code

// refer to the previous post for details and examples

}

public static function createRecords1(string $moduleAPIName) {

$recordOperations = new RecordOperations();

$bodyWrapper = new BodyWrapper();

$record = new Record();

$record->addFieldValue(Contacts::LastName(), "Boyle");

// custom multi-picklist

$record->addKeyValue("Event_Participation", [new Choice("Webinar"), new Choice("Trade Show")]);

//custom multi-lookup

$lookup1 = new Record();

$lookup1->addKeyValue("id", "5545974471152");

$multiSelectLookup1 = new Record();

$multiSelectLookup1->addKeyValue("Products", $lookup1);

$lookup2 = new Record();

$lookup2->addKeyValue("id", "554597771087");

$multiSelectLookup2 = new Record();

$multiSelectLookup2->addKeyValue("Products", $lookup2);

$record->addKeyValue("Products", [$multiSelectLookup1, $multiSelectLookup2]);

//multi-user lookup

$userlookup1 = new User();

$userlookup1->addKeyValue("id", "5545974393001");

$multiUserLookup1 = new User();

$multiUserLookup1->addKeyValue("Sales_Reps", $userlookup1);

$userlookup2 = new User();

$userlookup2->addKeyValue("id", "5545974492072");

$multiUserLookup2 = new User();

$multiUserLookup2->addKeyValue("Sales_Reps", $userlookup2);

$record->addKeyValue("Sales_Reps", [$multiUserLookup1, $multiUserLookup2]);

$bodyWrapper->setData([$record]);

$headerInstance = new HeaderMap();

$response = $recordOperations->createRecords($moduleAPIName, $bodyWrapper, $headerInstance);

//Add code to handle the response received in $response

// For more details, refer here.

}

CreateRecords::initialize();

$moduleAPIName = "Contacts";

CreateRecords::createRecords1($moduleAPIName);

3. Updating Related Records using External ID

For Related Records using External ID, define the external id information in the header as follows:

$xExternal = "Module.External_ID_Field_Name,Related_Module.External_ID_Field_Name";

$relatedRecordsOperations = new RelatedRecordsOperations($relatedListAPIName, $moduleAPIName, $xExternal);

Here is a sample code for linking the products with External_Product_ID (External ID field) PR01 and PR02 with a Lead with External_ID (External ID field) ABC123.

<?php

use com\zoho\crm\api\relatedrecords\BodyWrapper;

use com\zoho\crm\api\relatedrecords\RelatedRecordsOperations;

use com\zoho\crm\api\record\Record;

require_once "vendor/autoload.php";

class UpdateRelatedRecordsUsingExternalId {

public static function initialize() {

// add initialisation code

// refer to the previous post for details and examples

}

public static function updateRelatedRecordsUsingExternalId1(string $moduleAPIName, string $externalValue, string $relatedListAPIName) {

$xExternal = "Leads.External_ID,Products.External_Product_ID";

$relatedRecordsOperations = new RelatedRecordsOperations($relatedListAPIName, $moduleAPIName, $xExternal);

$request = new BodyWrapper();

$record1 = new Record();

$record1->addKeyValue("External_Product_ID", "PR01");

$record2 = new Record();

$record2->addKeyValue("External_Product_ID", "PR02");

$request->setData([$record1, $record2]);

$response = $relatedRecordsOperations->updateRelatedRecordsUsingExternalId($externalValue, $request);

//Add your code to handle the response received in $response

//For more details, refer here.

}

UpdateRelatedRecordsUsingExternalId::initialize();

$moduleAPIName = "Leads";

$externalValue = "ABC123";

$relatedListAPIName = "Products";

UpdateRelatedRecordsUsingExternalId::updateRelatedRecordsUsingExternalId1($moduleAPIName, $externalValue, $relatedListAPIName);

4. Uploading a file to the ZFS

You can upload a file to the ZFS directly using the absolute file path, or you can stream the file from external source using their APIs. Depending on the method, the StreamWrapper class initialisation arguments differs.

If you are using the stream method, use the filename and stream that you obtain from the external source's API response.

$streamWrapper = new StreamWrapper(filename, stream, null);

If you want to use the absolute file path, the first two arguments should be null, and provide the file path as the third argument.

$streamWrapper = new StreamWrapper(null, null, "provide_file_path_here");

Here is a sample code to upload a file to ZFS from the local drive using the second method.

<?php

use com\zoho\crm\api\ParameterMap;

use com\zoho\crm\api\file\BodyWrapper;

use com\zoho\crm\api\file\FileOperations;

use com\zoho\crm\api\util\StreamWrapper;

require_once "vendor/autoload.php";

class UploadFiles {

public static function initialize() {

// add initialisation code

// refer to the previous post for details and examples

}

public static function uploadFiles1() {

$fileOperations = new FileOperations();

$bodyWrapper = new BodyWrapper();

$streamWrapper = new StreamWrapper(null, null, "/Users/user-1/Downloads/zoho.png");

$bodyWrapper->setFile([$streamWrapper]);

$paramInstance = new ParameterMap();

$response = $fileOperations->uploadFiles($bodyWrapper, $paramInstance);

//Add your code to handle the response received in $response

//For more details, refer here.

}

UploadFiles::initialize();

UploadFiles::uploadFiles1();

If successful, the $response object would contain the file id.

5. File Upload Field and Image Upload Field

To upload an image to an image upload field, or a file to a file upload field, you must first upload the file to ZFS using methods described in section 4. Use the id from the response to upload to the respective field.

Here is a sample code to upload an image and a file to a image upload field and file upload field respectively, in Leads module.

<?php

use com\zoho\crm\api\HeaderMap;

use com\zoho\crm\api\record\BodyWrapper;

use com\zoho\crm\api\record\FileDetails;

use com\zoho\crm\api\record\RecordOperations;

use com\zoho\crm\api\record\ { Leads };

use com\zoho\crm\api\record\ImageUpload;

use com\zoho\crm\api\record\Record;

require_once "vendor/autoload.php";

class CreateRecords {

public static function initialize() {

// add initialisation code

// refer to the previous post for details and examples

}

public static function createRecords1(string $moduleAPIName) {

$recordOperations = new RecordOperations();

$bodyWrapper = new BodyWrapper();

$record = new Record();

$record->addFieldValue(Leads::LastName(), "Boyle");

$record->addFieldValue(Leads::FirstName(), "Patricia");

$record->addFieldValue(Leads::Company(), "Zylker Corp");

$imageUpload = new ImageUpload();

$imageUpload->setEncryptedId("39c17f1033cd120e62f8104c5450213ede77147fe6");

$record->addKeyValue("Image_Upload", [$imageUpload]);

$fileDetail = new FileDetails();

$fileDetail->setFileId("39c17f1033cd120e62f8104c545af0efea6cc3c67cabefb16");

$record->addKeyValue("File_Upload", [$fileDetail]);

$headerInstance = new HeaderMap();

$bodyWrapper->setData([$record]);

$response = $recordOperations->createRecords($moduleAPIName, $bodyWrapper, $headerInstance);

//Add your code to handle the response received in $response

// For more details, refer here.

}

CreateRecords::initialize();

$moduleAPIName = "Leads";

CreateRecords::createRecords1($moduleAPIName);

We hope that you found this post useful. Stay tuned for more of these!

If you have any questions, let us know in the comments below, or write to us at support@zohocrm.com. We would love to hear from you!

See you next week with more useful content.

Cheers!

Access your files securely from anywhere

Zoho Developer Community

New to Zoho LandingPage?

Access Zoho LandingPage

Zoho LandingPage Resources

New to Zoho Survey?

Access Zoho Survey

Latest Feature Updates

Explore our Pricing & Plans

Zoho Survey Resources

Android Mobile Surveys

Insurvey Blogs

Insight Blogs

Tips & Tricks

New to Zoho CRM Plus?

Deliver unforgettable customer experiences

ACCESS ZOHO CRM PLUS

New to Zoho CRM Plus?

Deliver unforgettable customer experiences

ACCESS ZOHO CRM PLUS

New to Zoho Marketing Plus?

Everything you need to run your marketing

ACCESS ZOHO MARKETING PLUS

New to Zoho Marketing Plus?

Everything you need to run your marketing

ACCESS ZOHO MARKETING PLUS

New to Bigin?

Signup Now

Access Bigin

Latest Feature Updates

Zoho Desk Resources

Desk Community Learning Series
Digest
Functions
Meetups
Kbase
Resources
Glossary
Desk Marketplace
MVP Corner
Word of the Day

Tout forum

France ZUGs

Zoho SalesIQ Resources

Topic Participants
Anu Abraham

Sticky Posts
Kaizen#162 : Add Tags and Open Pre-filled Email Drafts via Client Scripts
Hello everyone! Welcome to another informative Kaizen post. In this post, let us see how to accomplish the following using Client Script. 1. How to auto-tag a record based on field update? 2. How to Open a pre-filled email draft This post will provide
Client Script | Update - Introducing Commands in Client Script!
Have you ever wished you could trigger Client Script from contexts other than just the supported pages and events? Have you ever wanted to leverage the advantage of Client Script at your finger tip? Discover the power of Client Script - Commands! Commands
Extension Pointers - JS SDK series #4: Managing data from a widget using ZOHO.CRM.HTTP
Handling and managing the data between two applications is a major factor for an efficient business. There are a variety of ways to handle data between Zoho CRM and other third-party applications. You can use deluge CRM tasks, create connectors, use API
Kaizen #152 - Client Script Support for the new Canvas Record Forms
Hello everyone! Have you ever wanted to trigger actions on click of a canvas button, icon, or text mandatory forms in Create/Edit and Clone Pages? Have you ever wanted to control how elements behave on the new Canvas Record Forms? This can be achieved
Extension pointers for integrating Zoho CRM with Zoho products #8: Upload and manage Zoho Workdrive folders and files from within Zoho CRM
Keeping records on your customers and business prospects is essential for tracking data, conducting follow-ups, and running a business smoothly. When you use two separate applications, and store relevant data in each, checking and tracking data becomes