Hints & Tips

CRANQ Helps You Automate with AI

CRANQ helps you to take data from one place, process it in some way or augment it, and post it to other places. For example, analyse GMails you receive from a particular sender using OpenAI, and if appropriate, make Google Tasks out of them.

Automations typically require a number of incremental, sequential steps, for example:

1. Get Message Ids for a particular sender from my GMail
2. Extract the text of the GMail with the most recent Message Id
3. Send the text of the message to OpenAI and find any suggested tasks for me, and any relevant deadlines
4. Write the tasks to my default Google Task list

The trick to writing good automations in CRANQ is to think through the steps carefully.

Getting Started

1. Break your workflow into a sequence of small Steps

Each Step should do something distinct and simple like 'Get yesterday's date and return in this format:  2023-11-21' or 'Encode the provided URL'. Keeping the Steps simple and incremental makes them easier to 'debug'

2. Steps often have Inputs and / or Outputs

We pass data in and out of steps using Inputs and Outputs. Outputs contain the data generated by the Step. Inputs help the step to do something, and are often linked to the Outputs from previous Steps using the '🔗' control when you mouseover an Input.

3. Write detailed, but concise, Descriptions for your Steps

The Step 'Description' is what the AI uses to write the code for your Step. Specify exactly what you want to happen in the Description, but try to be as concise as possible. You will usually get better results from a short Description than a long one. Use examples when describing what you want as an Output (e.g. [data1, data2,data3,...], hh:mm:ss)

4. Iterate your Descriptions

CRANQ writes code based on your description. If your step doesn't work, try varying your description. Sometimes even very small changes (like adding punctuation or changing a word) can lead to working code

5. Check 'Latest SEO Workflows' for relevant Workflows and Steps

Latest SEO Workflows is a database of successful CRANQ steps 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 APIs

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.

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.

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.

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.

Using OpenAI within CRANQ

You may want to send a prompt to OpenAI from within CRANQ. To do this, 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 generates a string output. If you generate data using OpenAI, it will be returned in a string format. Even though that string data may look like machine-readable structured data, 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.'

Import Community Steps When Possible

The Latest SEO 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.

Copy on SEO Workflows
Paste Into the Step Panel

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

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.