README

A Craft CMS plugin that integrates Verbb's Formie with SAP Cloud Platform, enabling automatic submission of form data using SAP's dynamic schema format with OAuth 2.0 authentication.

⚠️ Beta Notice

This plugin is currently in active development and provided under the MIT License for testing purposes.

Licensing is subject to change. We are finalizing our licensing structure and some or all features may require a paid license when officially released on the Craft Plugin Store. Some plugins may remain free, others may offer free and Pro editions, or be fully commercial.

If you are using this plugin, please be aware that future versions may have different licensing terms.

Requirements

• Craft CMS 5.0 or greater
• PHP 8.2 or greater
• Formie 3.0 or greater

Features

• OAuth 2.0 Authentication - Secure authentication with SAP Cloud Platform
• Dynamic Schema Support - Sends form data in SAP's flexible JSON format
• Multi-Environment - Supports both staging and production environments
• Metadata Tracking - Automatically captures IP, user agent, UTM parameters, and more
• Field Mapping - Intelligent handling of all Formie field types
• Environment Variables - Secure credential management with autosuggest
• Header Field Mapping - Configure memberID, memberEmail, memberMobile, invoiceID

Installation

Via Composer

cd /path/to/project

composer require lindemannrock/craft-formie-sap-integration

./craft plugin/install formie-sap-integration

Using DDEV

cd /path/to/project

ddev composer require lindemannrock/craft-formie-sap-integration

ddev craft plugin/install formie-sap-integration

Via Control Panel

In the Control Panel, go to Settings → Plugins and click "Install" for Formie SAP Integration.

Environment Configuration

Add these to your .env file:

# Required OAuth credentials
SAP_CLIENT_ID=your_client_id_here
SAP_CLIENT_SECRET=your_client_secret_here

# Environment selection
SAP_ENVIRONMENT=staging

# Optional API URLs (can be configured in CP)
SAP_STAGING_URL=https://staging-api.sap.com/v1
SAP_PRODUCTION_URL=https://production-api.sap.com/v1
SAP_API_ENDPOINT=/customer-feedback

# Optional OAuth URLs
SAP_OAUTH_TOKEN_URL=https://api.sap.com/oauth/token
SAP_OAUTH_AUTHORIZE_URL=https://api.sap.com/oauth/authorize
SAP_OAUTH_SCOPE=customer_data:write,forms:submit

Configuration

Step 1: Create SAP Integration

1. Go to Formie → Settings → Integrations

2. Click New Integration and select SAP Cloud under CRM

3. Configure the integration:

   • Name: Give your integration a name (e.g., "SAP Production")
   • Client ID: Enter $SAP_CLIENT_ID (environment variable tip will appear)
   • Client Secret: Enter $SAP_CLIENT_SECRET
   • Environment: Enter $SAP_ENVIRONMENT or choose staging/production
   • API URLs: Configure or use environment variables
   • API Endpoint: Set to /customer-feedback or as provided by SAP
   • OAuth URLs: Configure or use environment variables

4. Save the integration

5. Test the connection using the Refresh button

Step 2: Enable for Forms

1. Edit your Formie form
2. Go to Integrations tab
3. Enable the SAP Cloud integration
4. Configure header field mapping:
   • Member ID Field: Map to your member ID field
   • Member Email Field: Map to your email field
   • Member Mobile Field: Map to your phone field
   • Invoice ID Field: Map to invoice/order field (if applicable)
5. Save the form

Data Format

The integration sends data in SAP's dynamic schema format:

{
  "header": {
    "memberID": "MTIzNDU2", // Base64 encoded
    "memberEmail": "dXNlckBleGFtcGxlLmNvbQ==", // Base64 encoded
    "memberMobile": "Kzk2NjEyMzQ1Njc4OQ==", // Base64 encoded
    "invoiceID": "INV-2025-001"
  },
  "submissionId": "12345",
  "formId": "contact_form",
  "formTitle": "Contact Form",
  "submissionDate": "2025-07-10T14:30:00.000Z",
  "metadata": {
    "ipAddress": "192.168.1.100",
    "userAgent": "Mozilla/5.0...",
    "referrer": "https://example.com",
    "language": "ar",
    "timezone": "Asia/Riyadh",
    "deviceType": "mobile",
    "utmSource": "google",
    "utmMedium": "cpc",
    "utmCampaign": "summer_2025"
  },
  "fields": [
    {
      "handle": "customer_name",
      "label": "Customer Name",
      "value": "أحمد محمد"
    },
    {
      "handle": "satisfaction_rating",
      "label": "How satisfied are you?",
      "value": 5
    }
  ]
}

Metadata Collected

Always included:

• Submission ID, Form ID, Form Title, Submission Date
• IP Address, User Agent, Language, Timezone
• Device Type (mobile/tablet/desktop)
• Submission URL

Included when available:

• Referrer URL
• UTM parameters (source, medium, campaign, content, term)

Field Type Handling

• Text/Textarea → String values
• Number → Numeric values
• Dropdown/Radio → Selected value
• Checkboxes → Array of selected values
• Date → ISO 8601 format
• Name → Combined first/last name
• Phone → Extracted phone number
• Email → Email address
• Rating → Numeric rating value
• File Uploads → Not included in SAP payload

Testing

See SAP_API_TEST_GUIDE.md for comprehensive testing instructions.

Quick Test

1. Test Connection

   • Save the integration and click Refresh
   • Check for connection success/error messages

2. Test Form Submission

   • Create a simple test form
   • Enable SAP integration
   • Submit the form
   • Check Formie's integration logs

Troubleshooting

Common Issues

Integration Not Appearing

• Ensure plugin is installed: php craft plugin/list | grep formie-sap-integration
• Clear all caches: php craft clear-caches/all
• Check plugin is enabled in Settings → Plugins

OAuth Authentication Errors

• Verify Client ID and Secret are correct
• Check OAuth URLs are accessible
• Ensure redirect URI is whitelisted in SAP console
• Verify environment variables are set correctly

Submission Failures

• Check API endpoint is correct
• Verify all required header fields are mapped
• Review Craft logs for detailed error messages
• Ensure SAP API is accessible from your server

Environment Variable Tips Not Showing

• Verify you're using autosuggestField in templates
• Check both suggestEnvVars: true and suggestAliases: true are set
• Clear compiled templates: php craft clear-caches/compiled-templates

Documentation Files

• README.md - This overview and setup guide
• SAP_API_TEST_GUIDE.md - Comprehensive API testing guide
• TODO.md - Development tasks and future improvements
• .env.example - Environment variable examples

Support

• Documentation: https://github.com/LindemannRock/craft-formie-sap-integration
• Issues: https://github.com/LindemannRock/craft-formie-sap-integration/issues
• Email: support@lindemannrock.com

License

This plugin is licensed under the MIT License. See LICENSE for details.

Developed by LindemannRock

Built for use with Formie by Verbb