States in Zoho Circuit

In Zoho Circuit, states are building blocks of a circuit that can perform tasks, make decisions, or simply pass the output from one state to another. You can build circuits with states using the drag and drop functionality in Builder View, or with simple JSON construction in Code View.

 

Zoho Circuit classifies states into two types

1. Flow Controls
   
2. Functional States 
   

Flow Controls lets you control the flow of your circuit. For example, using a flow control state called 'Pass', you can pass your input from one state to another; using states 'Success' and 'Failure', you can stop the execution of a circuit. 

Functional States helps you to execute business logic in circuits. You can achieve this by writing functions in the built-in editor, creating links for webhooks, or by associating a circuit within a circuit.

You can build your circuits with the states available in Flow Controls and Functional States. 

            

States consist of attributes. Some states are defined by using unique attributes. For example, the following is a sample circuit that consists of 'Pass' and 'Wait' state in Code View.

1. {
2.       "Pass State": {
3.             "start": true,
4.             "type": "pass",
5.             "next": "Wait State"
6.       },
7.       "Wait State": {
8.             "type": "wait",
9.             "next": "End",
10.             "duration": 3
11.       }
12. }

While the 'type' and 'next' fields are available in both the states, the 'wait' state consists of a unique attribute, 'duration'. Similarly, states are made up of common fields and unique fields. 

Common Fields of States

Name

All the states must have a unique name to identify them within the circuit. 

Type

The actual functionality of the state is referred in its type. The following types are supported:

1. Pass
   
2. Branch
   
3. Parallel
   
4. Wait
   
5. Batch
   
6. Success
   
7. Failure
   
8. Function
   
9. Webhook
   
10. Circuit 
    

Next

The name of the next state that has to be run after the completion of the current state is denoted using 'Next'. Except for the terminal states 'Success' and 'Failure', all the other states must have this field. The last state of a circuit must have 'End' as the value of its 'Next' field.

Start

Every circuit must have any one state with field value 'start: true'. Although states can be defined in any sequence, the order of execution depends on the 'start' and 'next' field. Hence, 'start' field has to be provided for the beginning state. However, only one state within a circuit is allowed to have this field value.

 

Apart from the common fields, states also share certain fields, such as Input Path, Output Path, and Result Path for Input and Output handling.

All fields and their values are case-sensitive. Once a value is defined, the exact value must be inputted throughout the circuit. 

Flow Controls

As the name suggests, Flow Controls aids you in controlling the course of direction of your circuit. 

Flow Controls consists of the following states:

1. Pass  - Transfers the input from one state to another
   
2. Branch - Decides between branches of execution based on input
   
3. Parallel - Performs simultaneous executions 
   
4. Wait - Inserts a delay for a specific time
   
5. Batch - Implements multiple group executions
   
6. Success - Terminate an execution returning Success
   
7. Failure - Terminates an execution returning Failure
   

                  

Pass

The Pass state passes its input from one state to another without performing any task. You can also use this state to inject data or modify the input data in your circuit.

             

To input data in Builder View, click the corresponding state, then select 'Input/Output'. Enter the key(in format '$.fieldname') in 'ResultPath' and the value within 'Result'. 

            

Similarly, in Code View you can directly add the parameters 'resultPath' and 'result' within the state. 

Pass state example:

1. "Get Job Details": {
2. "type": "pass",
3. "next": "Update Job Details",
4. "resultPath": "$.Jobdetails.Id",
5. "result": 112
6. },

For example, if the input to this pass state is:

1. {
2. "Agent": "Saira",
3. "Jobdetails":{
4.            "Issue": "Access failure",
5.            "Location": "CA"
6. },
7. "JobName": "JLP112"
8. }

Then, the output would be:

1. {
2.       "Agent":"Saira",
3.       "Jobdetails":{
4.             "Issue":"Access failure",
5.             "Id":112,
6.             "Location":"CA"
7.       },
8.       "JobName":"JLP112"
9. }

Branch

Add a state that can pass your input to a different state based on its value. This is similar to having an 'If else' or 'switch case'. In Builder View, you can define branches by selecting Add Condition.

Add Condition allows you to set the rule for the respective branch using 'Condition' and select the next state using 'Go To'.

The following 'Condition' operators are supported:

Operator	Description
&&	And
==	BooleanEquals
!=	Not
==	NumericEquals
>	NumericGreaterThan
>=	NumericGreaterThanEquals
<	NumericLessThan
<=	NumericLessThanEquals
||	Or
==	StringEquals

In Code View for Branch, each branch must have 'Condition' and 'Next' fields.

Branch state example:

1. "Add User Details": {
2.       "type": "branch",
3.       "next": "End",
4.       "branches": [
5.        {
6.             "condition": "$.value1 == 'new'",
7.             "next": "Add User"
8.       },
9.       {
10.             "condition": "$.value2 == 'available'",
11.             "next": "Update User"
12.       }
13.       ]
14. }

Parallel

Perform simultaneous executions using Parallel. For example, consider a scenario where you need to send an email and add requests in JIRA and Zoho Projects whenever a new ticket is raised. You can do all the three independently and simultaneously without waiting for one another using Parallel.

In Builder View, define parallel executions using 'Add Path'.

 

In 'Add Path', provide a unique name for the path using 'Name' and the state that needs to act as the root or starting point for the path using 'Start At'. Similarly, in Code View, along with the common fields, the paths are also defined with their unique name and root.

1. "Customer Details": {
2. "type": "parallel",
3. "next": "End",
4. "paths": [
5. {
6. "name": "Path1",
7. "root": "Check Address"
8. },
9. {
10. "name": "Path2",
11. "root": "Check Phone"
12. }
13. ]
14. }

Wait

A 'Wait' state inserts a specific delay into your circuit. In Builder View, you can define the wait period under 'Duration' in seconds.

Similarly, in Code View, you can add the wait time under the 'duration' field.

1. Wait state example:
2. "wait_five_seconds": {
3. "type": "wait",
4.                 "next": "SelectUsers",
5. "duration": 5
6. }

Batch

'Batch' state allows you to perform simultaneous group executions as batches.

   

A 'Batch' state contains the following configuration in Builder View:

1. Collection Path - Enter the key that contains the values to be processed by 'Batch' state in the input JSON.
   
2. Collection Variable - Provide any variable name. The values within the collection path will be operated on, using this name.
   
3. Bind Type - You can bind the batch state to a function, webhook, or circuit using 'Bind Type'.
   
4. Next State - Enter the state name to which the output of this state needs to be traversed.
   
5. No. of Jobs - Define the number of threads for the batch state.
   

In Code View, JSON details can be provided under fields 'collectionPath' and 'collectionVariable'. You can link a function, webhook or circuit using 'bind' and define the number of threads for batch using 'degree'.

1.  "New Job": {
2.                   "type": "batch",
3.                   "next": "End",
4.                   "collectionPath": "$.batchJob",
5.                   "collectionVariable": "jobDetails",
6.                   "bind": {
7.                         "type": "function",
8.                         "functionName": "new_dlgfn"
9.                   },
10.                   "degree": 5
11. }

Success

A 'Success' state can be used to terminate an execution. It comes handy when using a 'branch' state that don't do anything except to finish the circuit.

Since Success states are end states, they don't have a 'Next' state, and don't require an 'End' field.

Success state example:

1. "Complete Circuit": {
2.       "type": "success"
3. }

Failure

A 'Failure' state stops an execution of the circuit, marking it as failure. You can add a specific 'Error Message' and 'Reason' to help in debugging.

  

The equivalent fields added in Code View for adding failure details are 'errorMessage' and 'reason'.

Failure state example:

1. "New State 14": {
2.       "type": "failure",
3.       "errorMessage": "Invalid Input",
4.       "reason": "ErrorCode:348"
5. }

• Related Articles

• Introduction to Zoho Circuit

  What is Zoho Circuit? Zoho circuit is a platform for integrating microservices to create automated workflows. With sophisticated flow controls, you can create custom applications or processes as workflows, without writing any code. Workflows created ...

• Circuits

  The main purpose of Zoho Circuit is to build efficient circuits in the form of workflows to coordinate multiple microservices. Circuits are state machines that can trigger and track each step automatically, and retry when there are errors. Setting up ...

• Webhooks

  Webhook enables communication between third-party applications and Zoho Circuit. With webhooks, you can make API calls and notify the applications whenever an action takes place in Zoho Circuit. Set up webhooks in the following three steps: Create a ...

• Functions

  Function is a program script that performs a set of operations whenever invoked within an application. Set up functions in Zoho Circuit to actualize your business routines. Circuit's functions are serverless, where the cloud provider dynamically ...

• Activity

  Activity in Zoho Circuit lets you associate a code hosted elsewhere to your circuit. When the state 'activity' is reached in a circuit, the circuit waits for the activity to start and be completed. Once the activity is completed, it is communicated ...