Skip to Content

Vinyl Connectors

Overview

Vinyl Connector is a feature designed to connect two different Vinyl instances together and treat it like a Rule, import the Table and start using it.

As a Developer you can use Vinyl Connector to connect two different instances that are running on the same environment (Local) or across two different environments over HTTP (Remote). Steps to configure Local and Remote Vinyl Connectors are provided in this article.

If you are trying to solve for a Vinyl LP dependancy scenario, we recommend that you use the Table Inheritance or Extend Table feature and not use the Vinyl Connector to solve for this. The Extend Table feature allows you to easily cherry pick tables that you want to use from other Data Sources residing on the same instance or environment, and does not create a dependancy on any of the other apps when ready to bundle and ship your app LP.

An example of the Vinyl LP dependency scenario:
You have two Vinyl Data Sources residing on the same instance or environment and you are looking to join between Data Source A and Data Source B. If your app is using Data Source A and you want to use a table from Data Source B, and then you need to ship a version of app A, which just uses 1 table from app B, you need to bundle and ship both app A and B. Here again, the recommended way to solve for this type scenario is by using Extended Tables. This is a much simpler and better solution to use.

Warning

It is generally not recommended any customer work with Vinyl Connectors on their own without consulting with their dedicated Jitterbit consultant or contact first.

Local Vinyl Connector

The Local Vinyl Connector can be used to establish a connection from one relational data source to another, within the same environment.

1. Creating a Local Vinyl Connector

  • From the IDE, click on Data Servers
  • Click + Server from the Data Servers panel
  • Name your server connection
    • Best practice naming convention is to name the server 'Local Vinyl'
  • Select the Type Vinyl from the Server Settings section
  • Select the Vinyl Type Local
  • Click Save

2. Creating a Data Source using the Local Vinyl Connector

  • From the IDE, click Data Servers
  • Click to select the Local Vinyl entry from the Data Servers panel
  • Click the + Source button from the Data Sources panel
  • Click + Create Database
  • Name your Data Source in the Database Name field
    • Best practice naming convention is to name the Data Source as follows: [Data Source You're Connecting to] ([Application using the connector])
      • For example: If you were creating a local connector for Northwinds and connecting it to an application named My Application, the name would be: Northwinds (My Application)

  • Select the Data Source that you want to create a connection to in the Database Name Field

    Note

    You must select a relational database. A public table/data object is required in the Data Source for it to be selected as as the Database.

  • Click Next

  • Review the proposed updates and click Done

Note

We recommend creating a different data source each time you want to connect your application to another relational database.

For example: If you have two applications and you want to use a local Vinyl Connection to connect to Northwinds, you would create two data sources. Following our naming convention, they would be:

  • Northwinds (My Application 1)
  • Northwinds (My Application 2)

3. Allow Public Access to the Tables/Business Objects you want to use in your Connector

  • Navigate to the App Workbench for the app you want to use
  • Click the Business Layer Rules tile
  • Select the App Data Source to reflect the data source containing tables you will be marking with Public Access
  • Mark any Tables or Business Rules that you want to use in your connector as Public
    • To mark a table as Public, click the Open Record icon > click More > Edge Case > in the Public Access group, check to enable Allow Read and/or Allow Write
    • To mark a business rule as Public, double click on the Rule to navigate to the Rule Definition page > click More > Edge Case > in the Allow Public Access control set, check to enable Read and/or Write
      • Read will allow you to read the data in that table/object
      • Write will allow you to modify the date in that table/object

Note

We highly recommend that you do not modify the public table/business object once it has been made public and used in a connector. Please see the limitations section below for more information.

4. Import Tables/Business Objects into your Connector

  • Navigate to IDE, click Data Servers
  • Click to select the Local Vinyl entry from the Data Servers panel
  • Click the Details button from the Data Sources panel
  • Click the Import button, and Import again from Import Capabilities to import all tables you marked as public OR type the table name/business object name in the Import Pattern to only import a subset of the public Tables/Business Objects
  • Click Proceed and a background job will run to execute the task

5. Add your Local Vinyl Connector as a Data Source to your Application

  • Navigate to the App Workbench for the app you want to modify
  • Click the Data Sources tile
  • Click + Source
  • Select Link to existing source
  • Click Next
  • Locate the named Data Source created in step 2, and click Link Source
  • Review proposed update and click Done
  • Navigate to the App Workbench for the app you want to modify
  • Click the Data Sources button
  • Click to select the relational data base you want to link to
  • Click the Link Sources button for selected data source
  • Click Create and select the Local Vinyl Connector data source you added to your application in Step 6
  • Click the checkmark to save the record

Note

This will allow you to use tables and business objects from the local vinyl data source in business rules and XP CRUD rules that are built in the relational database.

This will also allow you to create XP CRUD rules with the source data source of the relational database and the target data source of your local vinyl data source. These XP CRUD rules will need to be built in the relational database.

  • Navigate to the App Workbench for the app you want to modify
  • Click the Data Sources button
  • Click to select the Local Vinyl connector you want to link to
  • Click the Link Sources button for selected data source
  • Click Create and select the relational data source you want to connect to
  • Click the checkmark to save the record

Note

This will allow you to use tables and business objects from the relational database in business rules and XP CRUD rules that are built in the local vinyl connector.

This will also allow you to create XP CRUD rules with the source data source of the local vinyl data source and the target data source of your relational data source. These XP CRUD rules will need to be built in the relational database.

Remote Vinyl Connector

The Remote Vinyl Connector can be used to establish a connection from one Vinyl environment to another over HTTP.

1. Create the object to share using Vinyl Connector

  • Navigate to the App Workbench from the app you want to share from
  • Click + Rule
  • Assign a Name for the rule. For example: Customer (Remote)
  • Set the Purpose. For example: Business Object
  • Confirm the Target. For example: Customer
  • Click Create
  • From the Tables tab, click to select the columns you want to display
  • Go to More > Edge Case
  • From Allow Public Access, check to enable Read and/or Write as appropriate
  • Click Proceed

2. Enable Remote Vinyl Connections

  • Navigate to the IDE
  • Click the Additional Settings button
  • Click the Remote Vinyl Connections button
  • Place a check in the Allow column for the application you wish to allow remote Vinyl Connections
  • Click Proceed

3. Confirm an API Key Security Provider is Configured

  • Navigate to the IDE
  • Click the Security Providers button
  • Confirm there is an Enabled API Key security provider configured. If not, one needs to be configured.
  • See Security Provider - API Key for more information

4. Create a Role to share the object

  • Navigate to the App Workbench for the app
  • Click the Roles tile
  • Click + Role
  • Assign a Name. For example: Remote Connector
  • Click Save
  • Click the + Permission button
  • Select the object created in step 1
  • Click the checkmark to save

Note

For more information on Roles, see Privileges & Permissions.

5. Create a Group and User

  • Navigate to the IDE
  • Click the User Management button
  • Select the Groups navigation tab
  • Click + Group
  • Assign a Name. For example: Remote Connector
  • Click Manage Priviledges > Create
  • Select Application as the Type
  • Select the appropriate Application from the menu. For example: Global Imports
  • Click Save
  • Click Create
  • Select Application as the Type
  • Select the appropriate Application from the menu. For example: Vinyl
  • Click the Grant button appearing for the application selected in the prior step
  • Click the Grant button for the Vinyl Remote Connector
  • Click the Users navigation tab and click + User
  • Assign a User Name. For example RemoteConnector
  • Click Save
  • Click the More button and select Keys
  • Click the Create button
  • Select the API Key as the Provider and click Save
  • Copy the generated Key value to the clipboard.
  • Click + Membership
  • Select the Group created (Remote Connector) and click the checkmark to save

Caution

The generated Key value cannot be retrieved after leaving the Generate Key screen. If the value is lost you will need to generate a new Key value.

6. Setup from the remote environment

  • Navigate to the remote environment you're looking to connect to
  • Go to the App Workbench from the app you're looking to connect
  • Click the Data Sources tile
  • Click + Source
  • Select New Connection and click Next
  • Select Other as the Connection Category
  • Locate and select Vinyl and click Next
  • Assign a Server Name. For example: Remote
  • Confirm Vinyl Type is set to Remote
  • Paste the Api Key value copied in step 5
  • Enter the Url value for the other environment you are connecting to. For example: https://example.com
  • Click Next, Next
  • Click Import Schema for the tables, views, and stored procedures you're looking to connect
  • Click Next and review proposed updates, then click Done
  • Select Remote Vinyl Connector Data Source, then click Logic
  • Click the Results icon for an entry appearing to confirm you see data
  • Test making an edit to a data record, save, and navigate back to the other environment and confirm you now see the update

Limitations and Callouts

  • Vinyl Connector does not support Reach
  • Vinyl Connector does support Audit, but Audit must be enabled on the underlying table in order to work
  • For Local Vinyl Connector, both databases must be relational databases and exist on the same server environment.
  • For Local Vinyl Connector, if you add/modify columns to public tables or business objects, you will need to manually keep the tables/business objects in sync.

Note

Best practice is to make new Business Objects that will only be used for the Vinyl Connector. Once you import the object, you should only change the public object if necessary. If you do change it, be sure to make the same change in the Local Vinyl Connector.

Troubleshooting

403 Forbidden Error

If you receive a 403 Forbidden error message with the Vinyl Connector, check to see you granted your user the "Vinyl Remote Connector" role. See the Create a Group and User section of this article for information on how to configure.

Full error detail:

Response status code does not indicate success
at void Vinyl.Business.Application.Events.RemoteEventRunner.AssertSuccessStatusCode(HttpResponseMessage response, string uri, EventTableRef eventTableRef)
at async Task<EventTableRef> Vinyl.Business.Application.Events.RemoteEventRunner.Invoke(EventTableRef eventTableRef, VinylConnectorEndpoint connectorEndpoint)
at async Task<EventTableRef> Vinyl.Business.Application.Events.RemoteEventRunner.InvokeCountAsync(EventTableRef eventTableRef)
at async Task<EventTableRef> Vinyl.DataSource.VinylConnector.VinylConnectorDataSourceServerHandler.CountPublicDataSourcesAsync(EventContext eventContext)
at async Task Vinyl.DataSource.VinylConnector.VinylConnectorDataSourceServerHandler.PingAsync(EventContext eventContext, CancellationToken cancellationToken)
at async Task Vinyl.DataSource.Plugins.DataSourceManagement.PingDataSourceServer.InvokeAsync(ValidationRule validationRule, EventInputRow input)

Reason
Forbidden
Status
403
Uri
https://{{VinylRootURI}}/connector/v1/count
Remote DataSourceId
19b4051a-b959-4b0c-9bd4-98b7cf2be132
Remote Table Name
DataSource_Public
Remote Event Name
null
Source
Vinyl.Business