Skip to main content

​
Publishing overview

Flow publishing in Phinite provides enterprise-grade deployment capabilities with full version control, access management, and observability. Understanding the publishing process is crucial for maintaining stable, secure, and auditable workflows.

​
Publishing workflow

​
Access control and permissions

Publishing flows requires “Admin” or “SuperAdmin” role. Users with “Developer” role can save flows but cannot publish them to production environments.

​
Role-based publishing permissions

RoleCan Save FlowsCan Publish to DevCan Publish to UATCan Publish to Prod
SuperAdmin✅✅✅✅
Admin✅✅✅✅
Developer✅✅❌❌
Tester❌❌❌❌
Viewer❌❌❌❌

​
Environment-specific access

  • Development: All users with “Developer” role or higher
  • UAT: Requires “Admin” role for publishing
  • Production: Requires “Admin” or “SuperAdmin” role with additional approval workflows

​
Pre-publishing checklist

​
Flow validation requirements

  • Flow is saved successfully
  • All required block fields are filled
  • Agent prompts are complete and tested
  • RAG sources are properly connected
  • Tool integrations are configured
  • Variables are properly mapped
  • Conditional edges have valid logic
  • Flow has clear Start and End blocks
  • No orphaned blocks or disconnected components

​
Common validation failures

Error: “Please fill all required details for the following blocks: agent, tool”Debugging steps:
  1. Check each block in the Inspector panel
  2. Verify all required fields are populated
  3. Look for red validation indicators
  4. Test blocks individually before publishing
Sample validation code:
// Check block validation
const validateBlock = (block) => {
  const requiredFields = {
    'task': ['name', 'task_prompt'],
    'api': ['toolid', 'name'],
    'flow': ['flowid', 'name']
  };
  
  const blockType = block.type;
  const missingFields = requiredFields[blockType]?.filter(
    field => !block.data?.details?.[field]
  );
  
  return missingFields || [];
};
Resolution: Fill all required fields and re-validate
Error: “Flow contains invalid connections or orphaned blocks”Debugging steps:
  1. Check for blocks without proper connections
  2. Verify Start block has outgoing connections
  3. Ensure End blocks have incoming connections
  4. Look for disconnected blocks in the canvas
Sample debugging code:
// Check flow connectivity
const validateConnections = (nodes, edges) => {
  const startNodes = nodes.filter(n => n.type === 'start');
  const endNodes = nodes.filter(n => n.type === 'end');
  const orphanedNodes = nodes.filter(n => 
    n.type !== 'start' && n.type !== 'end' && 
    !edges.some(e => e.target === n.id || e.source === n.id)
  );
  
  return {
    hasStart: startNodes.length > 0,
    hasEnd: endNodes.length > 0,
    orphanedCount: orphanedNodes.length
  };
};
Resolution: Connect all blocks properly and ensure flow integrity
Error: “Tool integration failed validation”Debugging steps:
  1. Check tool authentication in DevStudio
  2. Verify API keys and credentials
  3. Test tools independently
  4. Review tool parameter mapping
Sample debugging code:
// Test tool integration
const testTool = async (toolId, parameters) => {
  try {
    const response = await fetch(`/api/tools/${toolId}/test`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(parameters)
    });
    
    if (!response.ok) {
      throw new Error(`Tool test failed: ${response.statusText}`);
    }
    
    return await response.json();
  } catch (error) {
    console.error('Tool validation error:', error);
    throw error;
  }
};
Resolution: Fix tool configuration and authentication

​
Publishing process

Publish Pn

​
Step-by-step publishing

1

Save your flow

Click “Save” in the studio header to persist your changes.
You should see a success message confirming the flow is saved.
2

Run validation

The system automatically validates your flow before publishing.
If validation fails, you’ll see specific error messages indicating what needs to be fixed.
3

Add version details

Provide a clear description of changes in this version.Good version notes:
Version 2.1.0 - Customer Service Flow
- Added RAG integration for policy knowledge
- Improved error handling for payment failures
- Updated email templates for better customer experience
- Fixed issue with order lookup timeout
Poor version notes:
Updated stuff
4

Select target environment

Choose the appropriate environment for deployment.
Production deployments may require additional approval workflows depending on your organization’s policies.
5

Confirm and publish

Review all settings and confirm the publication.
You should see a success message and the new version in the version history.

​
Version management

​
Version history interface

The version history panel (Sidebar/canvas/VersionHistory.tsx) provides comprehensive version management:
  • Version list: View all published versions with timestamps and notes
  • Version details: Inspect specific version configurations
  • Copy to draft: Create a new draft based on any published version
  • Environment status: See which environments each version is deployed to

​
Version numbering

Phinite automatically manages version numbers:
  • First version: Starts at version 1
  • Subsequent versions: Incrementally numbered (2, 3, 4, etc.)
  • Draft versions: Not numbered until published
  • Version notes: Required for all published versions

​
Copying versions to draft

1

Access version history

Click “Version History” in the studio sidebar.
2

Select source version

Choose the version you want to copy from the list.
3

Copy to draft

Click “Copy to Draft” and confirm the action.
4

Edit and republish

Make your changes and publish as a new version.

​
Debugging publishing issues

​
Common publishing problems

Symptoms: Flow fails to publish with validation error messagesDebugging steps:
  1. Review the specific validation error messages
  2. Check each block for missing required fields
  3. Verify all connections are valid
  4. Test individual components before publishing
Sample debugging code:
// Comprehensive flow validation
const validateFlowForPublishing = (flow) => {
  const errors = [];
  
  // Check for required blocks
  if (!flow.nodes.some(n => n.type === 'start')) {
    errors.push('Flow must have a Start block');
  }
  
  if (!flow.nodes.some(n => n.type === 'end')) {
    errors.push('Flow must have an End block');
  }
  
  // Check block configurations
  flow.nodes.forEach(node => {
    if (node.type === 'task' && !node.data?.details?.task_prompt) {
      errors.push(`Agent block ${node.id} missing prompt`);
    }
    
    if (node.type === 'api' && !node.data?.details?.toolid) {
      errors.push(`Tool block ${node.id} missing tool configuration`);
    }
  });
  
  return errors;
};
Resolution: Address all validation errors before attempting to publish
Symptoms: Flow saves but version creation failsDebugging steps:
  1. Check network connectivity
  2. Verify user permissions
  3. Review server logs for errors
  4. Try publishing to a different environment
Sample debugging code:
// Test publishing API
const testPublishing = async (flowId, versionDetails) => {
  try {
    const response = await fetch(`/api/flows/${flowId}/publish`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${authToken}`
      },
      body: JSON.stringify({
        versionDetails,
        environment: 'dev'
      })
    });
    
    if (!response.ok) {
      const error = await response.json();
      throw new Error(`Publishing failed: ${error.message}`);
    }
    
    return await response.json();
  } catch (error) {
    console.error('Publishing error:', error);
    throw error;
  }
};
Resolution: Check permissions, network, and server status
Symptoms: Version created but deployment to target environment failsDebugging steps:
  1. Check environment configuration
  2. Verify environment-specific settings
  3. Review deployment logs
  4. Test with a simpler flow first
Sample debugging code:
// Check environment status
const checkEnvironmentStatus = async (environment) => {
  try {
    const response = await fetch(`/api/environments/${environment}/status`);
    const status = await response.json();
    
    return {
      isHealthy: status.health === 'healthy',
      lastDeployment: status.lastDeployment,
      activeVersions: status.activeVersions
    };
  } catch (error) {
    console.error('Environment check failed:', error);
    return { isHealthy: false, error: error.message };
  }
};
Resolution: Fix environment configuration or contact system administrator

​
Post-publishing monitoring

​
Deployment verification

1

Check deployment status

Verify the flow is successfully deployed to the target environment.
2

Test flow execution

Run test scenarios to ensure the flow works as expected.
3

Monitor performance

Use Observability tools to track flow performance.
4

Review logs

Check execution logs for any issues or errors.

​
Performance monitoring

  • Execution success rate: Track how often flows complete successfully
  • Response times: Monitor flow execution duration
  • Error rates: Identify common failure points
  • Resource usage: Track token consumption and API calls

​
Best practices

​
Version management

  • Descriptive notes: Always provide clear, actionable version descriptions
  • Incremental changes: Make small, focused changes rather than large overhauls
  • Testing: Thoroughly test flows before publishing to production
  • Rollback plan: Keep previous versions available for quick rollback

​
Security considerations

  • Access control: Regularly review who has publishing permissions
  • Environment isolation: Maintain strict separation between environments
  • Audit trails: Monitor all publishing activities for compliance
  • Secret management: Ensure sensitive data is properly secured

​
Performance optimization

  • Efficient flows: Design flows for optimal performance and resource usage
  • Monitoring: Set up alerts for performance degradation
  • Scaling: Plan for increased load and usage patterns
  • Optimization: Continuously optimize based on performance data

​
Integration with other components

​
Assistant integration

​
Observability integration

​
Environment management