Sources

To allow an application to read and/or write data in a node, a Source must be defined. This provides the application with access permissions through the use of an authorization token when the application attempts to interact with the data contained in one or more nodes.

On the Settings > Customers > Sources page, you can:

• View enabled and disabled sources.
• Create and configure sources.
• Modify sources.
• Disable sources.
• Delete a source.

Create a new source

In the platform, go to Settings > Customers > Sources > Create to create a new source.
Then, select the desired Provider.

Providers are the mechanisms used to interact with the data. An application's ability to read and/or write data depends on the type of Provider associated with the source. The most commonly used are:

• API
• Javascript
• Plan
• Send

Each provider has its own level of security:

• Trusted: read/write access.
• Untrusted: write access only.

Providers are generally considered trusted when they have a high level of security in the permissions granted by the tokens. During the creation of a new source, each available provider is shown with its associated and recognized security level.

After selecting the desired provider, in the Active Nodes section, choose the nodes you want the application to access.

The provider may also have additional properties. For example, the JavaScript provider requires the URL of all domains authorized to write to the node(s), while the API provider allows defining the IP address that can read and write data in the node.

Upon saving the new source, an authorization token is generated. The token can always be retrieved from the individual source tab, Settings > Customers > Sources, by clicking on the desired source. On this page, a new token can be created by selecting Refresh Token.

Create the API source

To use the token directly with an API call, create a source set for API.

The information to be entered includes:

• Name and Description.
• Nodes where the source can read and/or write.
• Provider properties > the list of IP addresses ranges allowed to read and write a given source, where to enter one or more authorized IP ranges to read and/or write data.

The API documentation is available here.

warning

Each API call can have content (customer or events) with a maximum size of 64kb.

Create the JavaScript source

To add JavaScript to a website and track all customer actions, it is necessary to create a JavaScript source.

The information to be entered includes:

• Name and Description.
• Nodes where the source can read and/or write.
• Provider properties, where to specify the URLs that can write to the source.

When a JavaScript source is created, a token is provided for use during the JavaScript integration.

JavaScript documentation for a site is available in the Data Model chapter.

Creating the Plan source

This source allows synchronizing most customer events with the Segments module (Plan) and associating extended properties with the appropriate field. For more information, refer to the Data Model chapter.

The information to be entered includes:

• Name and Description.
• Nodes, where the source can read and/or write. Provider options:
  • Select the appropriate tenant from the Tenant list.
• Provider properties:
  • Under Classifications, enter the names of the appropriate purchase event key and the value pairs to be exported to the Segments (Plan) module. Up to 15 classifications can be exported (up to 10 as strings and 5 as dates). More information on classifications is available here.
• In Map event's extended properties to Plan fields, proceed as follows:

  • Select an event category from the Segments (Plan) module, e.g., Purchases, and associate the listed extended properties with the appropriate Segments fields.

    This option allows extended customer properties to be used for segmentation purposes.

warning

After configuring the required mappings and completing the creation of the source, the related fields must be made visible in the Segments area and, for example, the displayed names may need to be updated. More details are available here.

Limitations

A Plan source can be created for a specific tenant only if a Send synchronization exists for the database already used by that tenant.

The following limitations are necessary to ensure data integrity and consistency across the platform. The limitations are based on the principle "one source : one node : one userdb."

• Only one Plan source can be created per node.
• A userdb can be synchronized with only one node with a Plan source.
• A Plan source can be created on a node only if a Send source is configured on the same node and both are synchronized with the same node.

Create the Send source

The Customers area is natively integrated with Send, so it is possible to automatically synchronize customer data and newsletter subscriptions almost in real time.

To activate this source, fill in the following fields:

• Name and Description.
• Node where the source can read and/or write.
• Provider Options, enter here:
  • the Group PK, which is the identifier of the Send platform to be synchronized;
  • the UserDb ID, which is the identifier of the Send database. and click Apply.

In the Map properties to Send fields section:

• A list of customer profile fields appears, each with its own dropdown menu based on the selected Send database.
• Select the desired Send fields to activate data synchronization. One or more paired fields must be selected.

In addition to customer data, it is possible to synchronize one or more newsletter subscriptions.
To activate synchronization, click +Add in the subscription synchronization panel:

• Enter the Subscription ID from the Customers area.
• Select the Send subscription system.
• Enter the Send Webform Code for this subscription.
• To add another subscription, click +Add.

info

Subscription synchronization fields are not available for aggregated nodes.

Subscription synchronization is bidirectional. This means that any changes made in the Customer area and/or Send are synchronized.

Edit a Source

To edit a source, go to Settings > Customers > Sources and open the source tab to modify.

It is possible to modify:

• The source Name.
• The Description.
• The nodes the application can access.
• Additional provider properties.

Click Save to save the changes.

Selecting Back to list cancels the ongoing source modification process.
Selecting Delete removes the source after confirmation.
Selecting Refresh Token will generate a new token.

Disable a Source

To disable a source:

• Go to Settings > Customers > Sources.
• Locate the desired source and click the three-dot icon.
• Click Disable.

Delete a Source

To delete a source:

• Go to Settings > Customers > Sources.
• Select the source to remove.
• Click Delete. A notification message appears.
• Click Confirm to proceed with deletion.

danger

The deletion action is irreversible and cannot be undone after confirmation.