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!



    • Recent Topics

    • To Do: shareable task links without login

      Hi! I’m using Zoho Mail and ToDo in my daily work, and I’ve run into one limitation that’s a real blocker for me. Right now, to share tasks with managers or directors, they need to have a Zoho account and be added to a group. In practice, many of them
    • Separate Items & Services

      Hi, please separate items and services into different categories. Thank you
    • Unable to edit or delete email address

      I signed up for free Zoho today. I usually am pretty good at understanding and configuring things like this, but your interface baffles me, and your online help is cryptic to say the least. I have spent hours just trying to set up a couple of email accounts in Zoho before pointing my domain MX records to Zoho. I solved some other issues on my own, but I can't figure out this latest problem: I have created two email addresses in Zoho. Let's call the first one myname@mydomain.com and the second one
    • Mastering Zia Match Scores | Let's Talk Recruit

      Feeling overwhelmed by hundreds of resumes for every job? You’re not alone! Welcome back to Let’s Talk Recruit, where we break down Zoho Recruit’s features and hiring best practices into simple, actionable insights for recruiters. Imagine having an assistant
    • We are unable to process your request now. Please try again after sometime or contact support@zohoaccounts.com

      I cannot sign up and return the error of we are unable to process your request now. Please try again after sometime or contact support@zohoaccounts.com
    • Multi-currency - What's cooking ?

      Hi,       We have been doing this feature for sometime and we would like to give you some glimpses of it.  Working with Multi Currency :        Multicurrency support gives you the ability to handle business transactions in multiple currencies. You can define a base currency for your organization and add more currencies with exchange rates based on the base currency.  Setup :        From the setup page, you can manage all the currencies supported by your organization.       Currencies page        
    • Integrating Chatbot with Zoho Creator Application

      Is it possible to integrate a chatbot with a Zoho Creator application?
    • How to reduce programmatically the image uploaded by user?

      I need a function that will automatically reduce the pixel dimension to 800 x 600 pixels / 180 resolution or (approx. 1.37MB) of image uploaded by user from digital camera, for example, 2271 x 1704 pixels /180 resolution or approx. 11.1MB. After the user selected the image, the function will able to detect if pixels is above 800x600, process the photo (crop/ reduce) and resume upload. Need help...  
    • Dark mode for Zoho Creator / Zoho CRM Code editor

      Hi Team, Is there any plans for Dark mode in Zoho creator / Zoho Crm code editor and development pages in pipeline?
    • Is there a way to make a button scroll down?

      Looking to have a button on a landing page scroll down to another section on the page. Any recomendations outside of coding?
    • Collective-booking event not added to all staff calendars

      We assign two staff to certain events. When the client books this event, it adds it to one staff calendar (the 'organiser') but not the other. How can I ensure all staff assigned to a collective booking get the event in their calendar? (A side note: it
    • ZOHO Android Client

      Hi, I installed the Android app, but it had an issue, so I reinstalled it. I was able to add multiple accounts, but now when I add the next account, it just duplicates the one I already have and will not even allow me to enter the info for another account.
    • I'd like to suggest a feature enhancement for SalesIQ that would greatly improve the user experience across different channels.

      Hello Zoho Team, Current Limitation: When I enable the pre-chat form under Brands > Flow Controls to collect the visitor’s name and email, it gets applied globally across all channels, including WhatsApp, Messenger, and Instagram. This doesn't quite align
    • Enhance Barcode/QR Code scanner with bulk scanning or continuously scanning

      Dear Zoho Creator, As we all know, after each scan, the scanning frame closes. Imagine having 100 items; we would need to tap 100 times and wait roughly 1 second each time for the scanning frame to reopen on mobile web. It's not just about wasting time;
    • Managing Rental Sales in Zoho Inventory

      I am aware that Zoho Inventory is not yet set up to handle rental sales and invoicing. Is anyone using it for rentals anyway? I'd like to hear about how others have found work arounds to manage inventory of rental equipment, rental payments, etc. Th
    • Megamenu

      Finally! Megamenu's are now available in Zoho-Sites, after waiting for it and requesting it for years! BUT ... why am I asked to upgrade in order to use a megamenu? First: Zoho promised to always provide premium versions and options for all included Zoho-applications
    • Zoho Flow to Creator 3001 Respoonse

      I have updated my Flows with the new V2 connection to Zoho Creator, but now some Flows do not work. They take in data from a Webhook and are supposed to create a record in Creator, however creator returns a 3001 message along with a failure, but I cannot
    • File Upload to Work Drive While Adding Records in Zoho Creator Application

      Hi I am trying to set a file attachment field in zoho creator form, to enable the user to upload a scanned document from their local pc. The file should be uploaded to zoho workdrive and not to the default zoho creator storage. The file link should be
    • Why not possible to generate?

      Using this https://desk.zoho.com/DeskAPIDocument#TicketCount#TicketCount_Getticketcountbyfield on my ZML script url :"https://desk.zoho.com/api/v1/ticketsCountByFieldValues?departmentId=XXXXXXXXXXX&accountId!=XXXXXXXXX&customField1=cf_country_1:XXXXXX&field=overDue"
    • email

      Hi My crm email is not working, can you check, I have zoho one account.
    • Need option to see Mass Emails & Cadences in Gmail Outbox OR a dedicated Zoho Outbox

      Hi everyone, Right now, when we send 1:1 emails from gmail (with gmail API connected to Zoho CRM), those emails appear both in gmail's sent folder and in Zoho CRM. That works well. But when we send Mass Emails or Cadence emails form Zoho CRM, they are
    • I can't found API for Sales Receipts

      Hello May you please help me to find an API document for Sales Receipts to get data and retrive a custom fields like Invoice and credit notes Regards
    • Kaizen #205 - Answering Your Questions | Managing Picklists and Enabling History Tracking via Zoho CRM APIs

      Hello everyone! Welcome back to another post in our Kaizen series. In this post, we will look at how you can manage picklist fields in Zoho CRM using APIs. This topic was raised as feedback to Kaizen #200, so we are taking it up here with more details.
    • Multiple Vendor SKUs

      One of the big concerns we have with ZOHO Inventory is lack of Vendor Skus like many other inventory software packages offer. Being able to have multiple vendor skus for the same product would be HUGE! It would populate the appropriate vendor Sku for
    • Internally created tickets

      Hi there When tickets are created internally on-behalf of customers - there is nothing to show that the ticket was created by an internal agent. This means, that it's easy for our agents to confuse tickets which were created by internal team members and
    • Automatically change website passwords

      Hi everyone, We just switched to a Professional package to also use the "Automatically change website passwords" function. But I cannot find anything about it, how to use it, anywhere. Does anyone know how I can use this function? Best, Caspar
    • Change Invoice Prices for an Effective Date

      Hi, It would be a really good feature to be able to change the prices on invoices/recurring invoices from an effective date in the event of price increases. For instance, I am in the process of increasing prices that will be effective from a specific
    • "Other Current Asset" accounts as "Paid Through" accounts in Expense

      It would be incredibly useful to be able to assign accounts of type Other Current Asset as Paid Through accounts in Expense. Currently, Other Current Liability are permitted as Paid Through Accounts. This makes sense, as Credit Cards are current liabilities.
    • Multi column open text questions that allows respondents to add rows for additional information

      I need to create a question that has 2 columns with open text, but I also need to allow respondents to click a "+" button, or something similar, so that they can add additional information if they choose to. I've tried using the Multiple Textboxes type
    • Bot Filtering & Apple Mail Privacy Protection Compliance in Zoho Campaigns

      Dear Campaigns Users, The wait is over! We’re excited to announce that the enhanced bot filtering feature is now live in Zoho Campaigns. This update brings greater accuracy to your email campaign reports by distinguishing real user engagement from automated
    • Découvrons les détails qui simplifient vos journées de travail avec Trident

      Nous nous installons dans des routines efficaces et rodées avec le temps. Chaque matin, nous ouvrons nos e-mails, passons aux messages, consultons notre agenda, puis attaquons nos tâches. Ce processus nous semble maîtrisé, mais est-il réellement optimisé
    • Issue with Purchase Rate Showing as “0” After Importing Items List

      Dear Zoho Books Support Team, Good day. I’m reaching out regarding an issue I’m facing while importing my items list into Zoho Books. Despite mapping all fields correctly and including the purchase price for each product in my Excel file, the Purchase
    • API for Task Entity in Zoho Books

      I’m working on automating task creation in Zoho Books via a custom button in the Bills Module. The goal is to create a task in the Tasks Module and assign it to the Finance Team, so they can track progress efficiently. While reviewing Zoho Books documentation,
    • create invoice in zoho books from the zoho forms

      Is there a native way to have create invoice in zoho books, when zoho form is completed?
    • Email undelivered

      GOod Day I am always receiving an uncategorized-bounce to my email. I am not sure why this is happening.
    • Add inventory_valuation_method to items endpooints

      To ensure consistent item creation it would be helpful to have the inventory_valuation_method (FIFO vs WAC) be able to be set at item creation or as an update (consistent with current behavior where it is not allowed for items with existing transactions)
    • Use Zoho to send sales receipts for Gocardless transactions

      I've been using gocardless for years and have d/d mandates set up on there. Each week we get bulk payments from customer d/d's. However, we need to send sales receipts to these customers. So I know I can sync mandates into Zoho, and then I can set up
    • Zoho - Gocardless sales receipts

      I've been using gocardless for years and have d/d mandates set up on there. Each week we get bulk payments from customer d/d's. However, we need to send sales receipts to these customers. So I know I can sync mandates into Zoho, and then I can set up
    • Introducing Rollup summary in Zoho CRM

      ------------------------------------------Moderated on 5th July'23---------------------------------------------- Rollup summary is now available for all organizations in all the DCs. Hello All, We hope you're well! We're here with an exciting update that
    • Introducing Connected Workflows in Zoho CRM for Everyone : Free Your Teams to Focus on What Matters

      Hello Everyone, We’re thrilled to introduce the next big evolution in Zoho CRM for Everyone -- Connected Workflows. This new feature builds on our commitment to deliver a CRM that’s truly inclusive, adaptable, and designed for consistent collaboration
    • Next Page