Configuring your Application

Create a New Project

Once your client has been registered, you can start creating your own iOS application.

In your command line, move to the directory where you want to create your mobile project and execute the following command.

This will prompt for the following user inputs.

1. Name of your Mobile App (For e.g., Lead Approver).
2. Your iOS developer organization name.
3. Your iOS developer organization identifier.
4. Zoho OAuth Client ID (obtained during app registration).
5. Zoho OAuth Client Secret (obtained during app registration).
6. Zoho OAuth Redirect URL (obtained during app registration).

On successfully executing the above command, a project folder will be created in the same directory. The name of the project folder will be the same as the Mobile App's name.

Run the Project

The newly created project is actually a demo iOS app, that can be run instantly using Xcode.

1. Open the .xcworkspace file of the newly created project.
   The newly created demo app will open as an Xcode project.
2. On successfully compiling, you can readily run this project into a simulator.
   The app will open up with a Zoho login screen in the simulator.
3. You can log in with your Zoho CRM credentials and view your data with the demo app.

Extend the app

Once your project is successfully built and run, you could further design and create new screens and functionalities for your app as per your requirements. There are no front-end restrictions in developing your app. However, to ease user authentication, please make sure to take note of the following points while designing your app.

Do not change any code that is already present in AppDelegate.swift

To handle log in/ log out:

To handle user login properly, launch screen is already configured in the SDK to make sure that only users who are logged in are able to view the data of the applications. However, if you want to show your own customized login screen, you can declare your own view as Launch screen.

In the ViewController class of your custom launch screen, add this code as the log in button's action:

Add this code as the log out button's action:

In the AppConfiguration.plist file

1. OAuthscopes (mandatory) - Samples scopes are already mentioned in the created property file, you can change the scopes as per your need.Learn more.
2. AccessType (optional) - Type of environment in CRM
   • Production - Environment that have active paying users accessing critical business data.
   • Development - Environments where you can extend, integrate and develop without affecting your production environments.
   • Sandbox - Environments specifically used for testing application functionality before deploying to production or releasing to customers.
3. DomainSuffix (optional) - Multi DC support.
   • us - www.zohoapis.com
   • eu - www.zohoapis.eu
   • cn - www.zohoapis.com.cn
4. PortalID (optional) - Mention your CRM PortalID (Ex : 65468393). No need to mention "PortalID" within properties file, if you do not have one.
5. ShowSignUp (optional) - Give the value as true if you provide signup facility in your app, else give false.

This file contains values of certain configurations that are needed to run the app. Please do not change the property names or values that already exist, as they are needed for the smooth functioning of the SDK and the app.

Zoho CRM API wrappers

All Zoho CRM entities are modeled as classes having members and methods applicable to that particular entity. ZCRMRestClient is the base class of the client library.

The class relations and hierarchy of the library follows the entity hierarchy inside Zoho CRM. The class hierarchy of various Zoho CRM entities is given below.

As appearing in the hierarchy, every entity class will have methods to fetch its own properties and to fetch data of its immediate child entities through an API call.

For example, a Zoho CRM module (ZCRMModule) object will have methods to get a module’s properties like display name, module ID, etc. and will also have methods to fetch all its child layout (ZCRMLayout) objects.

Accessing record properties

Since record properties are dynamic across modules, we have only given the common fields like createdTime, createdBy, owner, etc. as ZCRMRecord’s default members. All other record properties are available as a map in ZCRMRecord object.

To access the individual field values of a record, use the getter and setter methods available. The keys of the record properties map are the API names of the module’s fields. API names of all the fields from all the modules are available under Setup > Developer Space > APIs > CRM API > API Names.

• To get a field value, use record.getFieldValue(fieldAPIName);
  The returned value will be in the apt data type of the requested field. For lookup and user type fields, ZCRMRecord and ZCRMUser objects will be returned respectively.
• To set a field value, use record.setFieldValue(fieldAPIName, newValue);
  While setting a field value, please make sure that the set value is of the apt data type of the field to which you are going to set it.

Extensions provided:

In String:

• dateFromISO8601 : Date?
• dateComponents : DateComponents

In Date:

• iso8601 : String
• millisecondsToISO( timeIntervalSince1970 : Double, timeZone : TimeZone ) -> String
• millisecondsToISO( timeIntervalSinceNow : Double, timeZone : TimeZone ) -> String
• millisecondsToISO( timeIntervalSinceReferenceDate : Double, timeZone : TimeZone ) -> String
• millisecondsSince1970 : Double
• dateComponents : DateComponents

To download a user's profile picture:

The methods available in the SDK to achieve that are:

• ZCRMUser().downloadProfilePhoto()
• ZCRMUser().downloadProfilePhoto( size : PhotoSize )

Response Handling

APIResponse and BulkAPIResponse are wrapper objects for Zoho CRM APIs’ responses. All API calling methods would return one of these two objects.

A method seeking a single entity would return APIResponse object, whereas a method seeking a list of entities would return BulkAPIResponse object.

Use the getData() method to get the entity data alone from the response wrapper objects. APIResponse.getData() would return a single Zoho CRM entity object, while BulkAPIResponse.getData() would return a list of Zoho CRM entity objects.

Other than data, these response wrapper objects have the following properties.

1. ResponseHeaders — remaining API counts for the present day/window and time elapsed for the present window reset.
2. ResponseInfo — any other information, if provided by the API, in addition to the actual data.
3. [EntityResponse] — status of individual entities in a bulk API. For example, in an insert records, API may partially fail because of a few records. This list gives the individual records’ creation status.

Errors

All unexpected behaviors like faulty API responses, library anomalies are handled by the client library and are thrown only as ZCRMSDKError, with cases for apt errors. Hence, its enough to catch this error alone in the client app code.

SDK Data Access wrappers

In addition to the above wrapping of Zoho CRM APIs, in order to avoid unnecessary API calls, essential module metadata are cached by the SDK in the device’s local storage.

Currently, CRM data (records) are not cached and only metadata of modules such as layouts, sections, fields, and custom view details are cached.

ZCRMCachedModule

Some additional metadata caching is done with ZCRMCachedModule. This extends the ZCRMModule class of the Zoho CRM API Client Library. This class provides the following methods.

• getAllLayouts - returns all the layouts of the module as an array of ZCRMLayout.
• getAllCustomViews - returns all the custom view details of the module as an array of ZCRMCustomView.

Refreshing the Cache

ZCRMCachedModule store and use the metadata information of modules and form layouts cached in the device’s local storage. The SDK refreshes the stored metadata of a module for every 12 hours.

In case, you want to force the SDK to drop the cache (Example: If you intend to provide something like a swipe to refresh in your app) and refresh the metadata through a Zoho CRM API call, you can force it by setting the refreshCache flag provided in the overloaded versions of the above methods. Sample invocation is given below.