Integration Guide

SoftyFlow provides comprehensive integration capabilities that allow you to connect with external systems and services. This guide covers the three main integration methods available in SoftyFlow.

Before starting with integrations, ensure you've completed your project setup, understand database concepts, and know how to use integrations in your web interfaces and processes.

1. EDS API Integration (Outgoing Integrations)​

Overview​

External Data Sources (EDS) API integration allows SoftyFlow to consume external REST APIs as data sources. This enables seamless integration with third-party services and systems.

API EDS Configuration​

Configure API EDS to connect with external REST APIs:

Available API Endpoint Types​

• retrieve: Get single record by ID
• list: Get multiple records with pagination
• count: Count records matching criteria
• insert: Create new record
• insertMany: Create multiple records
• update: Update existing record
• delete: Delete record
• execute: Custom operations

Context Variables Available​

• SF_source: Data source and query parameters
• SF_table: Table/resource name
• SF_postData: Data for POST/PUT operations
• SF_limit: Maximum records to retrieve
• SF_sortby: Sort field name
• SF_page: Current page number
• SF_direction: Sort direction (1 or -1)

Complete API EDS Example​

Using API EDS in Actions​

Using API EDS in Widgets​

2. Scripts via Axios (Process Modeler SDK)​

Overview​

The Process Modeler SDK provides access to axios for making HTTP requests within process scripts, allowing for flexible API integrations during workflow execution.

Basic Axios Usage​

POST Requests​

PUT Requests​

DELETE Requests​

Authentication Examples​

Bearer Token Authentication​

API Key Authentication​

Complex Integration Example​

3. Incoming APIs (SoftyFlow APIs)​

Overview​

SoftyFlow allows you to create APIs that external systems can call, enabling inbound integrations and webhooks.

API Configuration Variables​

When creating SoftyFlow APIs, these variables are available:

• SF_body: Contains API body data
• SF_headers: Contains API header data
• SF_query: Contains API query data
• SF_mode: The execution mode of the API (test, uat, prod)
• SF_initiator: Contains the user who launched the API

Example API Implementation​

Advanced API Example​

// Advanced customer management API
let { action, customerId, customerData } = SF_body;
let authHeader = SF_headers.authorization;

// Authentication check
if (!authHeader || !authHeader.startsWith("Bearer ")) {
  return {
    error: "Unauthorized",
    status: 401,
  };
}

try {
  switch (action) {
    case "create":
      // Validate required fields
      if (!customerData.email || !customerData.name) {
        return {
          error: "Email and name are required",
          status: 400,
        };
      }

      // Check if customer exists
      let existingCustomer = await SF.collection.findOne("customers", {
        email: customerData.email,
      });

      if (existingCustomer) {
        return {
          error: "Customer already exists",
          status: 409,
        };
      }

      // Create customer
      let newCustomer = await SF.collection.insertOne("customers", {
        ...customerData,
        created_at: new Date(),
        created_by: SF_initiator._id,
      });

      return {
        success: true,
        customer: newCustomer,
        message: "Customer created successfully",
      };

    case "update":
      if (!customerId) {
        return {
          error: "Customer ID is required",
          status: 400,
        };
      }

      let updatedCustomer = await SF.collection.updateOne(
        "customers",
        { _id: customerId },
        {
          ...customerData,
          updated_at: new Date(),
          updated_by: SF_initiator._id,
        }
      );

      return {
        success: true,
        customer: updatedCustomer,
        message: "Customer updated successfully",
      };

    case "delete":
      if (!customerId) {
        return {
          error: "Customer ID is required",
          status: 400,
        };
      }

      await SF.collection.deleteOne("customers", { _id: customerId });

      return {
        success: true,
        message: "Customer deleted successfully",
      };

    case "get":
      if (customerId) {
        let customer = await SF.collection.findOne("customers", {
          _id: customerId,
        });
        return {
          success: true,
          customer: customer,
        };
      } else {
        let customers = await SF.collection.find("customers", {});
        return {
          success: true,
          customers: customers,
        };
      }

    default:
      return {
        error: "Invalid action",
        status: 400,
      };
  }
} catch (error) {
  return {
    error: "Internal server error",
    message: error.message,
    status: 500,
  };
}

Calling SoftyFlow APIs​

1. Using InvokeApi Action​

2. Using External HTTP Calls​

API Access Control​

• Configure access rights by selecting user groups
• Set APIs as public for external access
• Monitor API usage through logs
• Track API calls with user information and timestamps

API Testing​

SoftyFlow provides built-in API testing capabilities:

1. Define test variables in JSON format
2. Use the eye button to test during development
3. View results in the lower section
4. Monitor logs for debugging

Best Practices​

Security​

• Always validate input data
• Implement proper authentication
• Use HTTPS for all API communications
• Sanitize data before processing

Error Handling​

• Implement comprehensive error handling
• Return meaningful error messages
• Log errors for debugging
• Use appropriate HTTP status codes

Performance​

• Implement request timeouts
• Use connection pooling where applicable
• Cache responses when appropriate
• Monitor API performance

Documentation​

• Document all API endpoints
• Provide clear examples
• Maintain version compatibility
• Update documentation with changes

This comprehensive integration guide enables you to leverage SoftyFlow's full integration capabilities, whether you're consuming external APIs through EDS, making HTTP requests via axios scripts, or exposing SoftyFlow functionality through incoming APIs.

Next Steps​

Now that you understand integration, continue building your application:

• Web Interface Design - Create interfaces that use integrated data
• Process Design - Design processes that integrate with external systems
• Database Integration - Combine database and API integrations
• Reporting - Create reports from integrated data
• Test & Deploy - Test your integrations across environments
• Monitor & Run - Monitor your integrated processes

For hands-on experience, try our step-by-step tutorials and explore our reference guides for APIs, EDS, and SDK documentation.

For security considerations, review our authentication guide and user management documentation.