This file needs to be created manually or you can use our Data Catalog Connectors Template, which includes all the components recommended for connector development.

The labels and descriptions for graph parameters appear in the CloverDX Server UI.

Use clear and easy-to-understand parameter labels and descriptions to help administrators with the library setup.

Use the appropriate Editor types for your parameters, such as enums, numeric, or boolean, to simplify the library setup process for administrators.

It is not necessary to set all parameters as public, as all parameters in the file will be included in the CloverDX Server UI by default.

If you need to access these parameters, you can link the parameter file to your job file.

If values are set in this parameter file, they will be used in the job execution. However, the parameters can be overridden when the graph is executed. In that case, values specified in library.prm are considered default values.

Some of the parameter values, such as connection details, might be necessary for the library initialization. See Initialization Jobs (pre-generating metadata).

If a Data Source or Data Target Connector includes public parameters, they will be visible and configurable in the connector Configuration in CloverDX Wrangler. To help Wrangler users understand how to configure the parameters, provide clear labels, and descriptions, and select the appropriate editor types. If possible, use enums to prevent incorrect user input.

Every public job in a library should include a Note component with a short explanation of what the job does. This note should be separate (not encapsulate any components) and be visible when the job is opened (i.e., not too far down or to the right - usually top-left corner of the job is the best location).

Difficult and non-obvious parts of each job should be explained in notes as well. Keep in mind that even for libraries users can look inside in Job Inspector or via Designer when debugging.

Each public subgraph in a library project must have a description in the Properties tab. Do not include too much detail here and place the most important info at the beginning of the description. See Enhancing Library Look and Feel for more information.

readme.md - rendered markdown - (a layout used in the CloverDX Marketplace libraries​). You can use our Data Catalog Connectors template library, which includes a sample .md file for convenience.

readme.txt - plain text

readme - plain text

Subgraph name must be unique within the library; i.e., its name in the subgraph Properties must not exist in a different subgraph.

Subgraph cannot have any input port.

Subgraph must have exactly 1 output port.

Output metadata must be declared: either auto-propagated or statically assigned.

Output metadata can only contain fields of types: string, long, integer, date, decimal, number, and boolean to adhere to Wrangler’s requirements.

Subgraph must expose a parameter called NUM_OF_PREVIEW_RECORDS. This parameter is used to limit the number of returned records in the Data Preview when viewing connector details in the Data Catalog or My Sources, which considerably enhances preview performance.

Error handling with reasonable error messages propagated by the Fail component.

Alternatively, you can call the raiseError(string message) function directly from the CTL2 code. Make sure to use a descriptive error message.

Use secure graph parameters for sensitive input parameters such as passwords or tokens. Be aware that secure parameters are encrypted with your CloverDX Server master password and won’t work on another instance with a different master password.

Keep subgraphs small and focused on accomplishing a single task. Use several layers of subgraphs if needed (e.g. lower level subgraphs for core API calls, higher level subgraphs already specialized with business logic to simplify usage and eliminate complex or excessive configuration options). Don’t try to create connectors that would be too universal - create several simple ones instead. The CloverDX Data Catalog helps end users navigate among options to find the one most suited to their needs.

Consult with business users about their requirements and offer custom solutions for their business cases.

Prefer enums for parameters when possible. This helps users avoid input errors.

Design the Data Source Connector with Wrangler’s join limitations in mind. Prepare data that meets the needs of Business users.

For entities such as Customers, Contacts, Invoices, etc., include relevant references in the Data Source Connector.

Use parameters for the Data Source Connector if there are filters (e.g., valid/invalid records). This allows business users to easily adjust the data set returned by the connector.

Test thoroughly before publishing for users.

Subgraph name must be unique within the library; i.e., its name in the graph Properties must not exist in a different subgraph.

Subgraph must have exactly 1 input port.

Input port metadata is optional. Providing metadata on input port enables mapping in Wrangler. If metadata is specified on input port, it must contain a field called wranglerId of type long. This field is used to link your transformation data to errors reported by the target when generating the reject file.

Input metadata can only contain fields of types: string, long, date, boolean, and decimal (length=32, scale=10 only).

Subgraph may have 1 output port which will be used as a “reject” port to collect errors raised by the connector itself.

If a reject port is used, it must use metadata created from the edge template called ConnectorTarget_Rejects (right-click on your edge and navigate to New Metadata From Template > ConnectorTarget_Rejects). This metadata must not be modified.

If your target supports rejects, we recommend that you return rejected records using the optional reject port.

Propagate the same value as the wrangelerId input field to the output field. It serves as an identifier of records for the reject file generated by running the Wrangler job.

Try to describe the actual error message as descriptively as possible to help users resolve the error.

Consider how the data target reacts to existing data (append or re-write functionality) and failures (continue on error or stop processing).

If you do not define the input metadata, your data target should be able to process any input data. However, if you need to ensure that the data structure and data types are set correctly, assign the input metadata. Wrangler users will then set the data in the correct format. In any case, if your target needs any additional validations, implement them before writing to the target to help users with error handling.