For AI buildersThis page is written for AI assistants that build solutions on Plainly for a user. It's also a useful checklist for people. Follow it in order.
What you produce
A Plainly solution is made of text that the user pastes into Plainly. Produce each part in its own code block, labelled with where it goes:
| Part |
Where the user pastes it |
Format |
| Template text |
Template editor, in the document |
HTML with {{variables}} and [[STATEMENTS]] |
| Template fields |
Template editor, Variables panel |
--#: blocks. See Template field directives. |
| Signature blocks |
Template editor, signature settings |
--#: blocks. See Signature blocks. |
| Workflow code |
Workflow editor, Code tab |
--#item: blocks. See Workflow actions. |
| Launch form |
Workflow editor, Settings → Extra fields |
--#: blocks with ---appears_on:settings |
| Advanced settings |
Workflow editor, Settings → Advanced |
One --#: block |
| Dashboard page |
A Web page template |
HTML with [[INCLUDE=data]] and widgets |
Also give the user: the order to create things in (templates before the workflows that use them), the placeholders they must replace, and a short test plan.
Process
- Understand the process. Ask for, or confirm: the steps, who does each one, the decisions and what each depends on, the documents involved, who signs, who's emailed, and what data they want to report on.
- List the variables. For every value the solution uses, decide where it comes from: the launch form, an item's answer, a document, or a built-in variable.
- Draw the flow. Sketch the items and connections, including every branch, before writing code.
- Write the templates. Text, then fields, then signature blocks.
- Write the workflow. Items in the order they should appear, with two-sided connections.
- Write the launch form for every variable that isn't produced inside the workflow.
- Check everything against the checklist below.
- Give a test plan covering every branch.
Never invent
Leave these as clearly named placeholders in single braces, and tell the user to replace them:
- template keys: {offer_letter_template_key}
- workflow keys and API keys: {onboarding_workflow_api_key}
- document keys, dataset IDs and dataset keys: {contracts_dataset_id}
- email addresses and phone numbers you haven't been given: {hr_email}.
Single-brace placeholders aren't Plainly syntax, so they're easy for the user to find. Never use double braces for a placeholder: Plainly would treat it as a variable.
Hard rules
Workflow code
- Every item starts with --#item: and has a unique ---id of lowercase letters, numbers and underscores.
- Every connection is two-sided: the earlier item names the later one in ---outcome or ---filterN|outcome, and the later item names the earlier one in ---depends_on.
- An item can depend on only one item and can have only one outcome. Don't try to merge branches into one item: duplicate the shared steps in each branch with a shared ---alias, or use a stop (Blocker) item.
- An item with filters ignores ---outcome. Filters on one item must not overlap and should cover every possible answer.
- Question filters compare against the exact answer text in ---answerN|text.
- Items with no ---depends_on show as soon as the task starts. Use that for parallel steps.
- Items that only calculate or pass data are hidden, with ---done_at:1.
- get_document, include_document, hidden, text_output and redirect need ---done_at:1.
- Line breaks inside a directive are written ~~~. Never put a real line break inside a directive value.
- ---pass_variables is {key}_IS_{value}_AND_{key}_IS_{value}. Values mustn't contain _AND_ or _IS_.
- Item IDs and aliases must not match launch form field names.
Templates
- Use built-in variables where they fit: a_counterparty_name, a_counterparty_address, a_signatory_name, a_signatory_email, a_date_start, a_date_end, c_entity, c_name.
- Every other variable must be defined as a field, or passed in by the workflow.
- Give every optional variable fallback text, {{name|}} at least, or the document can't be locked.
- One condition per [[IF]]. No AND or OR. No IF inside IF. Test blanks with [[NOT=x]]. Test true/false values with (EQUALS true).
- Write literal braces or brackets as {{, }}, [[ and ]].
Forms
- Use the Form document type, ---collect_data:true on every field the recipient completes, and [[SUBMIT_BUTTON]].
Integrations
- Payload URLs must be https://. Use ---content_type:json for JSON APIs, with the JSON body in ---pass_variables.
- Never put real API tokens in workflow code you show the user. Use placeholders.
- API calls to Plainly are POST requests with parameters in the body.
Final checklist
Before giving the user the solution, check:
- [ ] Every ---outcome and ---filterN|outcome points to an existing ID, and that item's ---depends_on points back.
- [ ] Every ---depends_on points to an earlier item that names this item as an outcome.
- [ ] Every {{variable}} has a source: launch form, an earlier item ID or alias, alias:variable from a document item, or a built-in variable.
- [ ] Every template variable is a field, a built-in, or passed in ---pass_variables.
- [ ] Every signature block ID used in ---pass_variables exists in the template.
- [ ] Match types are in capitals and spelled correctly.
- [ ] No placeholder has been left in double braces.
- [ ] Every branch reaches an end: a final item, a Kill, or nothing more to do.
Machine-readable resources
| Resource |
Contents |
| https://plainly.com/llms.txt |
An index of every documentation page |
| https://plainly.com/llms-full.txt |
The full text of the documentation, in one file |
| https://plainly.com/plainly-reference.json |
Actions, directives, field types, match types, string formats, statements and API endpoints as JSON |
See AI worked example: employee onboarding for a complete solution built this way.