Quickstart Guide

Get your first integration running in minutes with this step-by-step guide.

Prerequisites

  • Active Retrieve Account: Access to the platform
  • API Credentials: Authentication details for the systems you want to connect
  • System Permissions: Appropriate access levels to read/write data in your platforms

Overview

This guide will walk you through creating a simple integration workflow that syncs customer data from an e-commerce platform to a CRM system.

Step 1: Access the Workflow Builder

  1. Log in to your Retrieve dashboard
  2. Navigate to the Integrations section
  3. Click "Create New Integration" button

Step 2: Understand the Workflow Structure

Retrieve uses a visual workflow builder where you connect nodes to create your integration pipeline. Each node represents an action and can include its own field mapping and custom transformation logic.

Your First Workflow

We'll create a workflow with two nodes to sync customer data:

  1. Node 1 (Pull): Retrieve customers from Shopify - includes field mapping and data transformation
  2. Node 2 (Push): Send customers to CRM - includes field mapping and validation

Step 3: Add Your First Node (Pull Data)

Select Integration Package

Choose the integration package for your first system (e.g., Shopify, Magento, NetSuite). The platform will load the available actions for that system.

Enter API Credentials

Each platform requires different authentication details. You have two options for configuring credentials:

Option 1: Node-specific credentials

Define credentials specifically for this node by using the node ID as a key:

{
  "node-1": {
    "shopify": {
      "api_secret_key": "your_api_secret_key",
      "admin_api_access_token": "your_admin_api_access_token",
      "host_name": "your-store.myshopify.com"
    }
  }
}

Option 2: General credentials

Define credentials generally, making them available to any node using this package:

{
  "shopify": {
    "api_secret_key": "your_api_secret_key",
    "admin_api_access_token": "your_admin_api_access_token",
    "host_name": "your-store.myshopify.com"
  }
}

Select Action

Choose what data to retrieve:

  • pull_customers - Fetch customer records
  • pull_products - Fetch product catalog
  • pull_orders - Fetch order data
  • And more...

Configure Field Mapping (Optional)

Retrieve provides flexible field mapping options through the UI. You can configure mappings in several ways:

1. Direct Field Mapping

Map a source field directly to a destination field using the visual mapper.

2. Static Values

Set a field to a constant value when it must always be the same. For example, if the target field status should always be 1, you can configure this in the UI.

3. JavaScript Functions for Fields

Add custom JavaScript logic to individual fields. Your function has access to three variables:

  • originalValue - The value from the source field
  • originalData - Object containing all values from the source
  • integrationConfig - Object with all configuration for this integration

Example field transformation function:

if (originalValue === "published") {
  return 1;
} else {
  return 0;
}

4. After Origin Function (Advanced)

For complete control over data transformation, use the After Origin Function. This receives the entire array of records from the API call and allows you to restructure the data however you need.

Available variables in this function:

  • job - Current job with data and metadata
  • integration - Integration configuration
  • integrationHelper - Helper functions
  • queueManager - Queue management utilities

Example transformation:

const data = job.data.data;

return {
  id: data.increment_id,
  customer_email: data.customer.email,
  customer_name: data.customer.first_name + " " + data.customer.last_name,
  total: data.items.reduce((sum, { price, quantity }) => sum + price * quantity, 0)
}

Add Rewrite Function (Optional)

Add custom logic to filter or transform data within this node:

// Filter out test customers
let data = job.data.data;
let filteredData = data.filter(customer => {
  return !customer.email.includes('@test.com');
});

return {
  jobStatus: 1,
  data: filteredData,
  message: `Filtered ${data.length - filteredData.length} test customers`
};

Step 4: Add Your Second Node (Push Data)

Click "Add Node" and connect it to your first node.

Select Integration Package

Choose the integration package for the next system (e.g., Salesforce, HubSpot).

Enter API Credentials

Example: Salesforce

{
  "client_id": "your_client_id",
  "client_secret": "your_client_secret",
  "username": "your_username",
  "password": "your_password",
  "security_token": "your_security_token"
}

Select Action

Choose the operation:

  • push_customers - Create/update customers
  • push_contacts - Create/update contacts
  • And more...

Configure Field Mapping

Map the data from the previous node to the format required by this system:

{
  "Email": "customer_email",
  "FirstName": "customer_name",
  "Phone": "customer_phone"
}

Step 5: Test Your Workflow

  1. Click "Run Test" button
  2. The system will execute the workflow with a small sample of data
  3. Review the results in the test output panel
  4. Check data at each node to verify transformations

Common Issues

Authentication Errors

  • Verify your API credentials are correct
  • Check that tokens haven't expired
  • Ensure your API user has the required permissions

Field Mapping Errors

  • Verify source fields exist in your data
  • Check for typos in field names
  • Ensure required fields are mapped

Step 6: Schedule Your Workflow

Set up scheduling to run your workflow automatically:

  • Every X minutes: For near real-time sync (e.g., every 15 minutes)
  • Hourly: At a specific minute past the hour
  • Daily: At a specific time (e.g., 9:00 AM)
  • Weekly: On specific days at a specific time
  • Custom Cron: Advanced scheduling with cron expressions

Step 7: Activate Your Integration

  1. Review all node configurations
  2. Click "Save" to save your workflow
  3. Toggle the integration to "Active" status
  4. Your workflow is now running on the specified schedule!

Understanding Nodes

Each node in your workflow can contain:

  • Action: The operation to perform (pull or push data)
  • Credentials: API authentication for the system
  • Field Mapping: Transform data structure within the node
  • Rewrite Function: Custom JavaScript for complex logic
  • Configuration: Node-specific settings and parameters

Next Steps

Now that you have a basic workflow running, explore more advanced features: