Executing Functions using API URLs | Online Help | Sigma

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

  1.  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.
  1. {
  2.    "app_install_id" : "12345678901234",
  3.    "zapp_uuid" : "4998cbb4-2b14-4c46-b8fa-1ba2084c2f13",
  4.    "version" : 1.0,
  5.    "app_scope_id" : "676543",
  6.    "integ_scope_id" : "123456", // service team installed org id
  7.    "service_app_id" : "22334455667777", // service team's app installed id
  8.    "request_method" : "POST",
  9.    "sigma_execution_domain" : "4998cbb4-2b14-4c46-b8fa-1ba2084c2f13.sigmaexecution.com",
  10.    "service_domain" : "orchetly.zoho.com",
  11.    "payload" : <request body>,
  12.    "parameters" : { "param1" : "value1", .... etc },
  13.    "headers" : { "header1" : "value1", .... etc },
  14.    "encapiKey" : "<IAM Org API Key>", // this is unique for each installation
  15. }

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
  1. custom_response parameter is FALSE
  2. custom_response parameter is TRUE

Case 2: DRE function with STRING return type
  1. custom_response parameter is FALSE
  2. custom_response parameter is TRUE
 
Case 1a: When return type is VOID and custom_response is FALSE
Status Code: 200
Content Type: application/json
  1. {
  2.  "result": {
  3.    "Tasks": [ ],
  4.    "message": {
  5.       "userMessage": [
  6.            "userMessage1",
  7.            "userMessage2".....          
  8.        ]
  9.    }
  10.  },
  11.  "unique_id": "6770d980-b77f-11ea-8566-e1b196a63afa",
  12.  "code": 3009,
  13.  "function_id": 247153000000022001,
  14.  "message": "Function Executed Successfully",
  15.  "status": "Success"
  16. }
 
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
  1. {
  2.  "result": {
  3.    "output": "return value",
  4.    "Tasks": [ ],
  5.    "outputType": "STRING",
  6.    "message": {
  7.        "userMessage": [
  8.            "userMessage1",
  9.            "userMessage2".....          
  10.        ]
  11.    }
  12.  },
  13.  "unique_id": "d71ec590-2ef7-11eb-9be9-05d86f610bcc",
  14.  "code": 3009,
  15.  "function_id": "177112000000016001",
  16.  "action": "saveAndExecute",
  17.  "message": "Function Executed Successfully",
  18.  "status": "Success"
  19. }
 
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

  1. returnObject should be a Map type.
  2. returnObject.statusCode should be one of the HTTP Status Code.
  3. returnObject.contentType should be a HTTP supported value.
  4. 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

  1. entity = Map();
  2. entity.put("id", 001);
  3. entity.put("name", "Helen");

  5. responseHeaders = Map();
  6. // add response headers if any

  8. customResponse = Map();
  9. customResponse.put("statusCode", 201);
  10. customResponse.put("contentType", "application/json");
  11. customResponse.put("responseHeaders", responseHeaders);
  12. customResponse.put("message", entity);

  14. return customResponse;

Response for the above script
Status Code: 201
Content Type: application/json
  1. {
  2.  "id": 001,
  3.  "name": "Helen"
  4. }

Failure Response

If the API execution fails, the response will be as follows:

Case 1:
Status Code: 412
Content Type: application/json
  1. {
  2.    "message": "Installation not found for given input."
  3. OR
  4.     "message": "Installation is in inactive state for given input."
  5. OR
  6.     "message": "App Version status is not allow function execution."
  7. etc
  8. }
 
Case 2:
Status Code: 500
Content Type: application/json
  1. {
  2.    "message": "Function execution failed"
  3. }

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.
  1. functionUUID = "46b39021-1234-1234-1234-b4a1683f9d0d";
  2. functionVersion = 3;

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

  6. ' use the invokeFunctionURL to register webhook on third-party tool, execute function, etc '