Executing Functions using API URLs
Executing a function via a REST API URL is now supported in Sigma. All you have to do is configure the Function Execution API URL with your function parameters. This helps to listen to third-party application events through webhooks and perform relevant actions.
This functionality is currently supported only for Zoho Desk and Zoho Projects' extensions.
Business Case
To sync two Project Management Software like Zoho Projects and Jira via Sigma, the Function Execution API can be used. To do this, a webhook with the function URL is configured in Jira's end, which in turn invokes the DRE function in Sigma every time the configured action occurs. Thus, you can allow Jira to create a task or a bug every time an issue is filed in Zoho Projects and vice versa.
Note that only the functions associated with installed extensions can be executed using this API. To execute a Sigma function, use *.sigmaexecution domain.
Function Execution API
- POST https://<APP UUID>.sigmaexecution.com/workspace/invokefunction
Parameters
* refers to mandatory fields
|
Name
|
Type
|
Description
|
|
auth_type *
|
String
|
Authentication type.
|
|
encapiKey *
|
String
|
Encrypted API key. Note that this must be encoded if tried on Postman API.
|
|
sigma_function_uuid *
|
String
|
ID of the sigma function to be executed.
|
|
sigma_function_version *
|
Double
|
Version of the sigma function to be executed.
|
|
integ_scope_id *
|
Long
|
Portal ID of the Zoho Service.
|
|
app_install_id*
|
Long
|
Installation ID of the extension.
|
|
custom_response
|
Boolean
|
Customize the response format.
|
Extra Parameters
Function Execution API allows 10 more dynamic request parameters to be configured along with above mandatory parameters. The parameters can be in the following format:
|
Name
|
Type
|
Format
|
|
Dynamic Parameters
|
String
|
[a-zA-Z0-9_-]+
|
Request Body
Only JSON and XML content types are allowed in request body.
Headers
Function Execution API allows a maximum of 30 headers, including HTTP default headers. These extra headers will be passed to the DRE function via input data with property as 'headers'.
Input Data Format for DRE Function
Input data will be passed to the function in JSON format, along with the Request Body, Headers and Extra Parameters, if any.
- {
- "app_install_id" : "12345678901234",
- "zapp_uuid" : "4998cbb4-2b14-4c46-b8fa-1ba2084c2f13",
- "version" : 1.0,
- "app_scope_id" : "676543",
- "integ_scope_id" : "123456", // service team installed org id
- "service_app_id" : "22334455667777", // service team's app installed id
- "request_method" : "POST",
- "sigma_execution_domain" : "4998cbb4-2b14-4c46-b8fa-1ba2084c2f13.sigmaexecution.com",
- "service_domain" : "orchetly.zoho.com",
- "payload" : <request body>,
- "parameters" : { "param1" : "value1", .... etc },
- "headers" : { "header1" : "value1", .... etc },
- "encapiKey" : "<IAM Org API Key>", // this is unique for each installation
- }
Success Response
Once the API executes successfully, the response can be obtained in 4 different types of response formats. These formats are based on the function's return type and custom_response parameter.
Case 1: DRE function with VOID return type
- custom_response parameter is FALSE
- custom_response parameter is TRUE
Case 2: DRE function with STRING return type
- custom_response parameter is FALSE
- custom_response parameter is TRUE
Case 1a: When return type is VOID and custom_response is FALSE
Status Code: 200
Content Type: application/json
- {
- "result": {
- "Tasks": [ ],
- "message": {
- "userMessage": [
- "userMessage1",
- "userMessage2".....
- ]
- }
- },
- "unique_id": "6770d980-b77f-11ea-8566-e1b196a63afa",
- "code": 3009,
- "function_id": 247153000000022001,
- "message": "Function Executed Successfully",
- "status": "Success"
- }
Case 1b: When return type is VOID and custom_response is TRUE
Status Code: 200
Content Type: application/json
No response body
Case 2a: When return type is STRING and custom_response is FALSE
Status Code: 200
Content Type: application/json
- {
- "result": {
- "output": "return value",
- "Tasks": [ ],
- "outputType": "STRING",
- "message": {
- "userMessage": [
- "userMessage1",
- "userMessage2".....
- ]
- }
- },
- "unique_id": "d71ec590-2ef7-11eb-9be9-05d86f610bcc",
- "code": 3009,
- "function_id": "177112000000016001",
- "action": "saveAndExecute",
- "message": "Function Executed Successfully",
- "status": "Success"
- }
Case 2b: When return type is STRING and custom_response is TRUE
Let's assume that the variable 'returnObject' is fetched from actual DRE response.
returnObject = actualResponse.result.output
Status Code: <returnObject.statusCode if present, otherwise 200>
Content Type: <returnObject.contentType if present, otherwise application/json>
Response Headers: <returnObject.responseHeaders will be appended if present>
Response Body: <returnObject.message if present>
Validations
- returnObject should be a Map type.
- returnObject.statusCode should be one of the HTTP Status Code.
- returnObject.contentType should be a HTTP supported value.
- returnObject.responseHeaders should be a key-value pair.
Note: If the validation fails, we will not throw errors. Instead, we will set default values.
Sample script to return custom response
- entity = Map();
- entity.put("id", 001);
- entity.put("name", "Helen");
- responseHeaders = Map();
- // add response headers if any
- customResponse = Map();
- customResponse.put("statusCode", 201);
- customResponse.put("contentType", "application/json");
- customResponse.put("responseHeaders", responseHeaders);
- customResponse.put("message", entity);
- return customResponse;
Response for the above script
Status Code: 201
Content Type: application/json
- {
- "id": 001,
- "name": "Helen"
- }
Failure Response
If the API execution fails, the response will be as follows:
Case 1:
Status Code: 412
Content Type: application/json
- {
- "message": "Installation not found for given input."
- OR
- "message": "Installation is in inactive state for given input."
- OR
- "message": "App Version status is not allow function execution."
- etc
- }
Case 2:
Status Code: 500
Content Type: application/json
- {
- "message": "Function execution failed"
- }
How to construct Invoke Function URL inside DRE function?
The input data object will be passed to DRE function. This object will have a property called sigma_execution_domain which holds sigma execution domain value. We can use this property to construct the Invoke Function URL.
- functionUUID = "46b39021-1234-1234-1234-b4a1683f9d0d";
- functionVersion = 3;
- invokeFunctionURL = "https://" + data.get("sigma_execution_domain") + "/workspace/invokefunction?sigma_function_uuid="+functionUUID+"&sigma_function_version="+functionVersion+"&integ_scope_id="+data.get("integ_scope_id")+"&app_install_id="+data.get("app_install_id")+"&auth_type=apikey&encapiKey="+data.get("encapiKey");
- ' use the invokeFunctionURL to register webhook on third-party tool, execute function, etc '
Access your files securely from anywhere
Zoho CRM Training Programs
Learn how to use the best tools for sales force automation and better customer engagement from Zoho's implementation specialists.
Zoho DataPrep Personalized Demo
If you'd like a personalized walk-through of our data preparation tool, please request a demo and we'll be happy to show you how to get the best out of Zoho DataPrep.
- Zoho Workerly Home
- Forums
- Connect With Us:
- Zoho Recruit Home
- Forums
- Connect With Us:
New to Zoho CRM Plus?
Deliver unforgettable customer experiences
New to Zoho CRM Plus?
Deliver unforgettable customer experiences
New to Zoho Marketing Plus?
Everything you need to run your marketing
New to Zoho Marketing Plus?
Everything you need to run your marketing
You are currently viewing the help pages of Qntrl’s earlier version. Click here to view our latest version—Qntrl 3.0's help articles.
New to Zoho Survey?
Zoho Sheet Resources
Zoho Forms Resources
New to Zoho Sign?
Zoho Sign Resources
Sign, Paperless!
New to Zoho TeamInbox?
Zoho TeamInbox Resources
New to Zoho ZeptoMail?
Zoho DataPrep Resources
Design. Discuss. Deliver.
New to Zoho Workerly?
New to Zoho Recruit?
New to Zoho CRM?
New to Zoho Projects?
New to Zoho Sprints?
New to Zoho Assist?
New to Bigin?
Related Articles
Triggers & Events
Triggers are configured to invoke function blocks when specific events occur in the application or Zoho service. For example, you can trigger a welcome email to a user when your extension is installed. The mail notification function is configured in ...Functions
Functions are the building blocks for developing an extension. They come handy for all server side customization. Sigma executes functions without additional infrastructure cost. External function calls can be done using rest APIs. You have to ...Create extensions using Zoho Sigma cloud editor
Sigma has introduced a cloud editor where users can build extensions for Zoho services . Upon selecting a Zoho service, the corresponding service’s plug-in manifest file will be pre-populated into Sigma’s editor as a new project, eliminating the need ...Create extensions using Command Line Interface(CLI)
Zoho Sigma helps you to build extensions for Zoho services in two ways: Building apps using the command line interface (CLI). You can use this method if you want to build an extension offline with your own code editor. Use Zoho Sigma cloud editor and ...About Sigma
As your company expands, you might add new business processes to your organization and recruit more employees. Having several tools to monitor the development will make managing the organization laborious. Also, if you have to juggle between many ...
New to Zoho LandingPage?
Zoho LandingPage Resources