Creating a Data Source

Creating a data source connects an external feed to FORJ so your strategies can react to real market data. The creation process is a guided wizard that walks you through provider selection, schema definition, and validation.

The Creation Wizard

Open Data Sources from the user menu in the sidebar, then click Create Data Source. The wizard has three steps:

Step 1 — Provider & Series Kind

Field	Description
Display name	A human-readable name for this source (e.g., TV EURUSD 5m Candles).
Provider	Where your data comes from — TradingView or Generic Webhook. This helps FORJ show you platform-specific setup instructions but does not affect how data is processed. See Provider and Venue.
Series kind	The type of data this source delivers — Candle series or Event series. This determines the required schema fields and the event types your strategies receive. See Series Kind and Required Fields below.

Step 2 — Schema & Sample Payload

This is where you define the shape of the data your source will send and verify that FORJ can correctly parse it.

Stream Identity

For Candle series sources, you provide the canonical identity fields that describe the stream:

Field	Description	Example
Instrument	The trading symbol.	EURUSD, BTCUSD
Timeframe	The candle interval.	1m, 5m, 1h
Venue	The broker or exchange.	OANDA, Binance

Event series sources do not require canonical identity fields.

Schema Builder

The schema builder lets you define every field in your incoming JSON payload. For each field, you configure:

Setting	Description
Payload field name	The key in the JSON payload (e.g., close, data.candle.timestamp).
Display label	A human-readable name for the field.
JSON path	For nested payloads, a dot-notation path override (e.g., data.candle.close).
Data type	Number, Text, Boolean, or Timestamp.
Timestamp format	If the data type is Timestamp: Epoch seconds, Epoch milliseconds, or ISO-8601 string.
Role	The canonical role this field plays (see Field Roles below).
Required	Whether the field must be present in every payload. Auto-enabled for engine-required roles.

Preset buttons — "Add core candle fields" and "Add core event fields" bulk-add the standard fields with roles pre-assigned, saving you from configuring each one manually.

Field Roles

Every field in the schema is assigned a role that tells FORJ what the field represents:

Role	Applies To	Description
Timestamp	Both	When the event occurred. Required for both series kinds.
Open	Candle	The candle's open price.
High	Candle	The candle's high price.
Low	Candle	The candle's low price.
Close	Candle	The candle's close price.
Volume	Candle	The candle's volume.
Instrument	Candle	The trading symbol (e.g., EURUSD).
Timeframe	Candle	The candle interval (e.g., 5m).
Venue	Candle	The broker or exchange.
Event Type	Event	The name of the custom event (e.g., signal_fired). Required for event series.
Custom	Both	Any additional field you want to include. Multiple fields can have this role.

All roles except Custom are unique — only one field per schema can hold each role.

Sample Payload

Paste a sample JSON payload into the editor — this is an example of what your provider will actually send. FORJ uses it to:

• Auto-detect schema fields — the "Fill schema from sample" mapping tool parses your JSON, infers data types and field roles from key names (e.g., timestamp maps to the Timestamp role, close maps to Close), and populates the schema builder automatically.
• Test the mapping — before you can proceed, you must run a mapping test that applies your schema to the sample payload and confirms FORJ can extract all required fields correctly.

You can also work in the opposite direction — "Fill sample from schema" generates a sample JSON payload from your current schema definition.

Schema Workflow Guide

A progress indicator tracks your position through the schema step:

1. Stream identity — set the canonical identity fields (candle series only).
2. Define schema — add and configure fields with roles.
3. Sync schema & sample — ensure the schema and sample payload are consistent.
4. Test mapping — run the mapping test and confirm it passes.

The mapping test must pass before you can proceed to the review step.

Step 3 — Review & Create

The review step shows summary cards for everything you've configured. FORJ validates that:

• Provider and series kind are selected.
• Display name is valid.
• Schema and sample payload are valid JSON.
• All required field roles are assigned.
• Canonical identity is complete (candle series).
• The mapping test has passed and is up to date.

If any validation fails, blockers are shown with descriptions. The Create Data Source button is only enabled when everything passes.

Once created, the data source is immediately Active and FORJ generates a unique webhook URL that you configure in your data provider.

Series Kind and Required Fields

The series kind you choose determines which field roles are required:

Candle Series

For standard OHLCV market data. Required:

• Timestamp — when the candle closed.
• Instrument, Timeframe, Venue — the stream identity.
• At least one of Open, High, Low, Close — price data (all four are recommended).

Volume is optional but recommended. These fields are protected and cannot be removed from the schema.

Event Series

For custom event payloads from webhooks or external signals. Required:

• Timestamp — when the event occurred (if omitted, FORJ uses the current time).
• Event Type — the name of the event, which your strategy's transitions match against.

All other fields are optional. You can include any number of Custom fields to pass additional data that your strategy's conditions and actions can reference.

Configuring Your Provider

After creating the source, set up your external provider to send data to the webhook URL.

TradingView

1. In TradingView, create or edit an alert.
2. Set the Webhook URL to the URL FORJ generated for your source.
3. Configure the alert message body to include the required fields in JSON format, matching the schema you defined.
4. Activate the alert.

Generic Webhook

Send HTTP POST requests to the webhook URL with a JSON body. The field mapping you configured tells FORJ how to extract the data it needs. Any system that can send HTTP POST requests with JSON can serve as a data provider.

Staying Informed with Platform Alerts

You can subscribe to platform alerts to be notified about data source events — such as when a source is created, encounters an ingestion error, or recovers from an error. This is especially useful for workspace administrators managing multiple data streams.

Available data source alert events:

Event	When It Fires
Data Source Created	A new data source is created in your workspace.
Data Source Disabled	A source is manually disabled.
Data Source Reactivated	A disabled source is re-enabled.
Data Source Marked for Deletion	A source is scheduled for deletion.
Data Source Force Deleted	A source is permanently removed.
Data Source Error	An ingestion error occurs (e.g., payload doesn't match the schema).
Data Source Recovered	A source that was in an error state starts receiving valid data again.

To subscribe, go to Alerts and create a Platform Alert Subscription selecting the data source events you care about. You can choose delivery channels including in-app notifications, email, SMS, or webhook. See Configuring Alerts for details.