Skip to main content

​
What is a use case?

A use case is Codika’s deployment unit. It is a folder on disk that contains everything needed to deploy one or more n8n workflows as a single automation to the Codika platform. When deployed, a use case becomes a Process that users can discover, install, and run with their own credentials.

​
Folder structure

my-use-case/
  config.ts                    # Required: deployment configuration
  version.json                 # Required: semantic version (auto-managed)
  project.json                 # Optional: platform project ID and org ID
  workflows/
    main-workflow.json         # Required: at least one workflow
    helper-workflow.json       # Optional: sub-workflows
  deployments/                 # Auto-created: deployment archives
    {projectId}/
      project-info.json
      process/
        {apiVersion}/
          deployment-info.json
          config-snapshot.json
          workflows/*.json

​
Required files

FilePurpose
config.tsExports WORKFLOW_FILES, getConfiguration(), and optionally getDeploymentInputSchema() and getDefaultDeploymentParameters()
version.jsonTracks the local semantic version (e.g., {"version": "1.2.3"}). Updated automatically on deploy.
workflows/*.jsonn8n workflow JSON files. Each file listed in WORKFLOW_FILES is packaged and sent to the platform.

​
Optional files

FilePurpose
project.jsonContains projectId and organizationId. Created by codika-helper init or codika-helper project create --path .. Enables org-aware profile selection.
deployments/Local archive of past deployments. Created automatically by codika-helper deploy.

​
config.ts structure

The config file must export these members: 
import { loadAndEncodeWorkflow } from '@codika-io/helper-sdk';
import { fileURLToPath } from 'url';
import { dirname } from 'path';
import crypto from 'crypto';

const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename);

// Required: array of workflow file paths (relative to config.ts)
export const WORKFLOW_FILES = [
  'workflows/main-workflow.json',
  'workflows/helper-workflow.json',
];

// Required: returns the full deployment configuration
export function getConfiguration(): ProcessDeploymentConfigurationInput {
  return {
    title: 'My Automation',
    subtitle: 'One-line description of what it does',
    description: 'Longer description of capabilities and benefits.',
    workflows: [
      {
        workflowTemplateId: 'main-workflow',
        workflowId: 'main-workflow',
        workflowName: 'Main Workflow',
        integrationUids: ['anthropic', 'google_gmail'],
        triggers: [/* trigger definitions */],
        outputSchema: [/* output field definitions */],
        n8nWorkflowJsonBase64: loadAndEncodeWorkflow(
          __dirname, 'workflows/main-workflow.json'
        ),
        cost: 10,
      },
    ],
    tags: ['email', 'ai'],
  };
}

​
Configuration fields

FieldTypeRequiredDescription
titlestringYesDisplay name (2-5 words)
subtitlestringNoOne-line tagline
descriptionstringYes1-2 sentences describing the automation
workflowsarrayYesArray of workflow configurations
tagsstring[]NoCategorization tags
processDeploymentMarkdownstringNoMarkdown documentation for the process

​
Workflow configuration fields

FieldTypeRequiredDescription
workflowTemplateIdstringYesUnique identifier for the workflow
workflowIdstringYesMust match the workflowId parameter in Codika Init node
workflowNamestringYesDisplay name
integrationUidsstring[]YesRequired integrations (e.g., ['google_gmail', 'anthropic'])
triggersarrayYesAt least one trigger definition
outputSchemaarrayYesOutput field definitions (empty array [] for sub-workflows)
n8nWorkflowJsonBase64stringYesBase64-encoded workflow JSON
costnumberNoExecution cost in credits (0 for sub-workflows)
markdownInfostringNoWorkflow-specific documentation

​
Version management

The version.json file tracks a semantic version: 
{
  "version": "1.2.3"
}
On each deploy, the CLI:
  1. Reads the current version
  2. Bumps it based on the flag: --patch (default), --minor, or --major
  3. Sends the API version to the platform (X.Y format)
  4. Writes the new version back to version.json
Local bumpExampleAPI version strategy
--patch (default)1.0.0 → 1.0.1minor_bump
--minor1.0.1 → 1.1.0minor_bump
--major1.1.0 → 2.0.0major_bump
--version 3.0Any → explicitexplicit (version 3.0)

​
Relationship to platform entities

When you deploy a use case, the platform creates linked records: 
Use case folder
  → Process (public listing, discoverable)
    → Deployment template (immutable version snapshot)

  → Process instance (user installation with settings and activation state)
    → Deployment instance (running copy with live n8n workflow IDs)
See Processes for full details on the deployment lifecycle.