Hints & Tips

Break Your Workflow Into Distinct, Incremental Steps

The key to a successful workflow is building it up incrementally, so you can see where the problems are and debug them.

For example:  

Analyse GMails you receive from a particular sender using OpenAI, and if appropriate, create any requested jobs as Google Tasks

You can break that down into the following CRANQ workflow:

Writing Effective Descriptions

1. Descriptions are what CRANQ uses to create your Steps
How you write your Description, and the names of Inputs and Outputs, will dictate whether your Step works or not. Titles are not used by the system, so you can name your Steps whatever makes sense to you and your colleagues.

2. Brevity wins
Counter-intuitively, the more you write in a Step Description, the harder it is for the AI to know what to build. The Description should express the core of what you want the step to achieve, with a minimum of superfluous wordage.

3. Give examples of what you want a Step to output

Giving examples of desired outputs in a Step Description really helps the AI to know what you want. For example:

[data1, data2,data3,...]
[{"key":"value", "key":"value"},{...}]

4. If Steps aren't working, try re-generating them
If a Step won't run, but it seems to make sense to you, try making a small change in the Description (e,g, adding a full stop), and clicking Proceed. The code will be re-generated, and may start to work. Prompting LLMs is as much art, and guile, as science!

5. Check 'Latest SEO Workflows' for relevant Workflows and Steps
Community Workflows is a database of successful CRANQ Steps and workflows that have been generated and run on the CRANQ platform. Look for similar Steps to your own and Import them, or copy / paste them, or use successful Descriptions to inform your own Descriptions

Using OpenAI within CRANQ

CRANQ lets you use OpenAI natively within CRANQ, via CRANQ's own account.

To send a prompt to OpenAI from within CRANQ, write your description in this format:

'Send the following prompt to OpenAI:

"....your prompt..."
If you want to add variables to your prompt, then provide them as Inputs, and reference them with curly brackets, for example:

'Send the following prompt to OpenAI:

"Write a tweet about {subject}"
with the subject provided as an Input, and called 'subject'.

Important: OpenAI only takes a string input, and also often generates a string output. String data may look like machine-readable structured data, but you won't be able to feed it into another API.

To fix the string problem, if you generate data using OpenAI, insert an additional step afterwards with a description such as:'I provide you with a string. Please parse the string and return in JSON format.'

Manipulating Data

There's a few ways that developers use to format and describe data in javascript, and it's helpful to use these in your descriptions.

A simple comma-separated list of items within square brackets
[item1, item2, item3, ...]

A comma-separated series of key-and-value pairs within curly brackets
{key1:value1, key2:value2, key3:value3}

An array of Dictionaries, or
A comma-separated series of dictionaries (or 'records'), each of which is delineated by curly brackets
[{key1:value1, key2:value2, key3:value3},{key1:value1, key2:value2, key3:value3},...]

Data Manipulation
The method of manipulating data structures (returning values, appending new key-pairs etc.) is a basic programming skill, and one that we don't have space to explore here.

The video below is a good example of data manipulation over multiple Steps.

Use the Error Hints

CRANQ gives you full AI hints to support you in building your automation. The

Go to Error Hints from the Error Alert
The Hints are AI-powered and very useful, specific to your workflow

Import Community Steps When Possible

The Community Workflows page is your database of useful steps created by others. When you Copy a step from that database to your clipboard, you can then Import that Step into your own Flow. This is a useful shortcut because not only does it copy the description, but also the working code.

Import on Workflow Page
Confirm the Import


CRANQ makes it very easy to access APIs, with the number of supported APIs growing continuously. For example, CRANQ supports nearly all of Google's APIs via OAuth2.

To access an API, simply specify that you want to use it in your Description. For example:  'Tweet the provided text' or 'Download my 5 most recent message Ids from Gmail'. For some APIs, CRANQ will prompt you to provide OAuth2 permission, but for others you may need to provide an API key and account Id as an input. Usually you will have to register with that site separately beforehand.

If the API is 'RESTful' format, then even if CRANQ has never used it, you may be successful by specifying the Endpoint in the Description, and adding each of the Headers as Inputs.

Of course , APIs provide a valuable range of functions, but don't support every need. Sometimes, you might find that the data you want is not available from an API, or that it won't execute the action you want.

Don't Get Stuck, Ask for Help on Discord

There are many reasons why your step might not be working. It could be that the method, or scope is not supported by the relevant API, or that the API isn't known to the LLMs we use. Or it could be that we haven't registed for OAuth2 permission for that API yet.

If you are having real trouble, and have tried lots of different prompts for the same idea, get in touch on Discord, we're help to help.