Kaizen #85 - PHP SDK [Part II]

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");
  1.  $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"));
  1. $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"));
  1. $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);

  1. $lookup = new Record();
  2. $lookup->addKeyValue("id", "554597402674230");
  3. $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);
  1. $lookup = new Record();
  2. $lookup->addKeyValue("id", "55459742674230");
  3. $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);
  1. $recordOwner = new User();
  2. $recordOwner->setEmail("patricia.boyle@zylker.com");
  3. $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

        All-in-one knowledge management and training platform for your employees and customers.







                              Zoho Developer Community



                                  Bootcamp
                                  Community
                                  Pricing
                                  Webinars
                                  What's New
                                  Integrations
                                  Contact Support
                                  Contact Sales
                                    Zoho Survey Resources
                                      Features
                                      Survey Templates
                                      Integrations
                                      Community
                                      iOS Mobile Surveys
                                      Pricing
                                      Android Mobile Surveys
                                      Insurvey Blogs
                                      Insight Blogs
                                      Tips & Tricks





                                                  Latest Feature Updates

                                                    • Desk Community Learning Series


                                                    • Digest


                                                    • Functions


                                                    • Meetups


                                                    • Kbase


                                                    • Resources


                                                    • Glossary


                                                    • Desk Marketplace


                                                    • MVP Corner


                                                    • Word of the Day


                                                    • Ask the Experts




                                                        Zoho SalesIQ Resources

                                                              • Sticky Posts

                                                              • Kaizen #198: Using Client Script for Custom Validation in Blueprint

                                                                Nearing 200th Kaizen Post – 1 More to the Big Two-Oh-Oh! Do you have any questions, suggestions, or topics you would like us to cover in future posts? Your insights and suggestions help us shape future content and make this series better for everyone.

                                                              • Kaizen #226: Using ZRC in Client Script

                                                                Hello everyone! Welcome to another week of Kaizen. In today's post, lets see what is ZRC (Zoho Request Client) and how we can use ZRC methods in Client Script to get inputs from a Salesperson and update the Lead status with a single button click. In this

                                                              • Kaizen #222 - Client Script Support for Notes Related List

                                                                Hello everyone! Welcome to another week of Kaizen. The final Kaizen post of the year 2025 is here! With the new Client Script support for the Notes Related List, you can validate, enrich, and manage notes across modules. In this post, we’ll explore how

                                                              • Kaizen #217 - Actions APIs : Tasks

                                                                Welcome to another week of Kaizen! In last week's post we discussed Email Notifications APIs which act as the link between your Workflow automations and you. We have discussed how Zylker Cloud Services uses Email Notifications API in their custom dashboard.

                                                              • Kaizen #216 - Actions APIs : Email Notifications

                                                                Welcome to another week of Kaizen! For the last three weeks, we have been discussing Zylker's workflows. We successfully updated a dormant workflow, built a new one from the ground up and more. But our work is not finished—these automated processes are


                                                              Manage your brands on social media
                                                              Access Zoho Social

                                                                Zoho Pagesense Resources


                                                                    Zoho TeamInbox Resources

                                                                      Zoho DataPrep Resources


                                                                        Zoho CRM Plus Resources

                                                                          Zoho Books Resources


                                                                            Zoho Subscriptions Resources

                                                                              Zoho Projects Resources


                                                                                Zoho Sprints Resources


                                                                                  Qntrl Resources


                                                                                    Zoho Creator Resources



                                                                                        Zoho CRM Resources

                                                                                        • CRM Community Learning Series

                                                                                          CRM Community Learning Series


                                                                                        • Kaizen

                                                                                          Kaizen

                                                                                        • Functions

                                                                                          Functions

                                                                                        • Meetups

                                                                                          Meetups

                                                                                        • Kbase

                                                                                          Kbase

                                                                                        • Resources

                                                                                          Resources

                                                                                        • Digest

                                                                                          Digest

                                                                                        • CRM Marketplace

                                                                                          CRM Marketplace

                                                                                        • MVP Corner

                                                                                          MVP Corner









                                                                                            Design. Discuss. Deliver.

                                                                                            Create visually engaging stories with Zoho Show.

                                                                                            Get Started Now


                                                                                              Zoho Show Resources

                                                                                                Zoho Writer

                                                                                                Get Started. Write Away!

                                                                                                Writer is a powerful online word processor, designed for collaborative work.

                                                                                                  Zoho CRM コンテンツ




                                                                                                    Nederlandse Hulpbronnen


                                                                                                        ご検討中の方