•••
 
Documentation   /   For AI builders   /   AI builders guide
 
 

AI builders guide

 
For AI builders

This 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

  1. 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.
  2. 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.
  3. Draw the flow. Sketch the items and connections, including every branch, before writing code.
  4. Write the templates. Text, then fields, then signature blocks.
  5. Write the workflow. Items in the order they should appear, with two-sided connections.
  6. Write the launch form for every variable that isn't produced inside the workflow.
  7. Check everything against the checklist below.
  8. 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.