Skip to main content

​
Prepare a research document

The plugin works best when it has a clear understanding of the systems and requirements involved. Before starting, gather:
  • API documentation links for each system you want to integrate
  • Authentication details — which auth method each system uses (API key, OAuth 2.0, etc.)
  • Data models — the objects and fields you need to map between systems
  • Example payloads — sample API requests and responses help the plugin generate accurate transformations
  • Trigger requirements — whether the integration should run on webhook events, a schedule, or manually
Start your prompt with a research document or a detailed description of the integration. The more context you provide upfront, the fewer iterations you will need.

​
Write effective prompts

Be specific about what you want to build. A good prompt includes:
  • The systems involved — name the source and target platforms
  • The trigger type — webhook, schedule (with cron expression), or manual
  • Field mappings — which fields in the source map to which fields in the target
  • Authentication methods — how each system should authenticate
  • Edge cases — what should happen when records already exist, when fields are missing, or when API calls fail
Good prompt: 
Build an integration between HubSpot and Salesforce.
When a new contact is created in HubSpot (webhook), check if they exist in Salesforce by email.
If they exist, update the record. If not, create a new lead.
Use OAuth 2.0 for both systems.
Map: HubSpot firstname → Salesforce FirstName, HubSpot lastname → Salesforce LastName,
HubSpot email → Salesforce Email, HubSpot company → Salesforce Company.
Vague prompt: 
Sync contacts between HubSpot and Salesforce.
The vague prompt will still work, but the plugin will need to make assumptions about trigger type, field mappings, and authentication — leading to more back-and-forth.

​
SDK patterns the plugin uses

The plugin generates code using the Versori Run SDK. Understanding these patterns helps you review and refine the generated workflows:
  • Workflows & triggers — webhook and schedule-based entry points for integrations
  • Task types — the building blocks of workflows: functions, HTTP calls, and more
  • Context & KV storage — how workflows access connections, logging, and persistent state
  • Durable workflows — long-running workflows with persistent state across executions

​
Common integration patterns

The plugin handles a variety of integration patterns. These guides cover common use cases in detail:
Always review generated code before deploying to production. While the plugin follows best practices and generates tested code, you should verify that field mappings, authentication configuration, and error handling meet your specific requirements.

​
Troubleshooting

If the plugin is not activating or behaving as expected:
  • Check the CLI is authenticated — run versori context list to verify you have an active context
  • Ensure a project exists — the plugin will guide you through creating one, but you can also create one manually with versori projects create
  • Check your prompt — the plugin activates on integration-related tasks. If your request is about something unrelated, it will not engage
  • Update skills for other tools — if using downloaded skills, re-run versori skills download --latest to get the latest version