29. Libraries


    A CloverDX library is a redistributable package, which can contain reusable graphs, subgraphs, jobflows, data services, or metadata. Libraries offer significant improvements to code reusability and sharing in CloverDX. Because libraries can be installed multiple times, they provide an easy option to quickly clone your solutions and set them up with different parameters and permissions to control users' visibility and allowed operations for individual libraries.

    Libraries are developed in CloverDX Designer as projects, which are then exported to a library .clib file, and deployed to CloverDX Server. Depending on the options selected during library export, and assigned permissions, components from installed libraries become available for use in CloverDX Server, CloverDX Designer, or CloverDX Wrangler.

    You can design your libraries or take advantage of our ready-to-use libraries in the CloverDX Marketplace repository, which includes solutions to quickly integrate with interfaces like Hubspot or Google Drive, or solutions that can help you easily encrypt and decrypt your data or implement Python scripts.


    Libraries are developed as regular projects in CloverDX Designer. When the development is finished, the developer can export the whole project into a library .clib file. During the export, the author selects which elements will be public, i.e., available to all users after the library is installed and enabled in CloverDX Server. We call these elements the library public interface.

    Public elements can be:

    • Graphs and jobflows

    • Subgraphs

    • Data Services

    • Metadata

    Other elements in the exported project will be internal and will be used as sub-routines in the public ones.


    Graphs, Jobflows

    When creating a new schedule or event listener in CloverDX Server, installed libraries are available in the Sandbox dropdown, and public graphs and jobflows from the libraries are available to be selected for scheduling.

    library scheduling
    Figure 110. Libraries in schedulers
    Initialization Jobs

    A graph or jobflow can be used as a library initialization job to set up a configuration that cannot be set ahead of time during the development, e.g., generating data based on the provided connection to the source system. For example, in our CloverDX Marketplace OneDrive library, an initialization graph is used to generate values for SharePoint Site ID and Drive ID parameters, which are dependent on the configured OAuth2 connection.

    Initialization jobs must be designed to be run repeatedly. This may be necessary, for example, when changing the library configuration. For more information see Initialization Jobs.


    Public subgraphs from installed libraries come up in the Component Palette in server projects in CloverDX Designer, allowing you to easily add library subgraphs during the development process.

    library palette
    Figure 111. Libraries in Component Palette

    Data Source Connectors

    Data Source Connectors are special subgraphs designed to be used as data sources in the Data Catalog in CloverDX Wrangler.

    Data Services

    Data services from installed libraries can be deployed in CloverDX Server.

    library data service
    Figure 112. Libraries Data Services


    When developing new graphs in CloverDX Designer, public metadata from installed libraries can be linked as shared metadata by opening the context menu of the Metadata group in the Outline pane and selecting New metadata  Link shared definition from library.

    library metadata
    Figure 113. Libraries metadata


    Libraries can be installed in the Libraries module in the CloverDX Server console. Only users assigned to a user group that has one of the following permission combinations are allowed to install libraries:

    Installed libraries create a special type of public shared sandbox with read-only permissions. Internally, the packages are unpacked into the ${libraries.home} directory, which, by default, points to the libraries sub-directory located in ${sandboxes.home}. See sandboxes.home and libraries.home for more information.

    Libraries to be installed can be loaded by either selecting a single .clib file from a local directory or by selecting them to be installed from a library repository.

    Single Library Upload

    To load a single library for installation from a local directory click on the dropdown next to the Install library from repository button, and select the desired .clib file to be loaded.

    library single library upload

    Library Repository

    Library repositories allow you to share your libraries. A repository is a local or remote directory with .clib archives, each containing one library. When browsing libraries in a repository, users can easily see additional information like the library version, library description, or its public elements on the Overview tab. If a library includes a documentation page, it will be displayed on a separate Documentation tab.

    library repository
    Figure 114. Library repository

    Repositories can be local or remote. Currently, we support the following remote protocols: FTP, SFTP, Amazon S3, Azure Blob Storage, SMB, and SMB2.

    In CloverDX Server, you can add one or more repositories by using the Add repository button and then browse through the repositories and install selected libraries.

    Our CloverDX Marketplace, which includes a collection of CloverDX libraries that implement various functionalities, is automatically added during CloverDX Server installation with an empty database. For existing Server installations, the CloverDX Marketplace repository can be added by clicking on the Add CloverDX Marketplace button. After performing this step, the button will become disabled and will indicate that the repository has already been added. The CloverDX Marketplace repository (its URL is az-blob:// can be located in the Repository dropdown.

    Installation Settings

    When a library is selected to be installed, the following settings are available:

    • Enable switch: this switch defaults to False. We recommend installing all new libraries with this option disabled. Once a library is enabled, all public elements from the library become available for use by all authenticated users of the Server. Installing new libraries as Disabled will prevent users from using the libraries until they are fully configured. The state of the library (Enabled/Disabled) can be changed at any time in the list of installed libraries by a user assigned to a user group that has the following permissions combination:

    • Library ID: If not populated, it defaults to the Library Name entered during library export. Setting a different Library ID will allow you to install the same library version multiple times. See Installation Logic for more information. Library ID does not have to be populated if you only need one instance of the library. Library IDs cannot be changed after installation.

    • Label: If not populated, it defaults to the Library Name entered during library export. Setting a different label will change the library name in all the places where the library is used (CloverDX Designer Component Palette, Data Catalog in CloverDX Wrangler, or schedulers or listeners in CloverDX Server). Labels of installed libraries can be changed on the Overview tab of a library detail after clicking on the Edit button. See Library Editing for more information.

    • Overwrite already installed libraries: this option can be used to overwrite an installed library, if the library name, version, and library ID match. See Installation Logic for more information.

    Note that the library Version is not editable; it comes up as specified during library export.

    library installation settings
    Figure 115. Library installation

    Installation Logic

    The Libraries module offers great variability when installing libraries, which allows you to:

    1. Overwrite an existing library with an updated version of the same library.

    2. Install multiple library versions.

    3. Install the same library multiple times.

    This provides administrators with flexibility when managing libraries: libraries can be quickly installed, updated, or copied, and each installed library instance configured with different parameters or permissions.

    • To overwrite an already installed library, the library name, version, and library ID of the new library need to match, and the Overwrite already installed libraries option needs to be selected when installing such a library. If the Overwrite already installed libraries option is not selected, the matching (already installed) libraries are skipped.

    • To install a new library version, export the library project with a different version: When exporting a project to a library in CloverDX Designer, the library version needs to be specified. The version then comes up in the list of installed libraries next to the library name. If the library project is updated and exported with a new version, when installing the new library version a new library instance will be created. Multiple versions of the same library can co-exist and be utilized as needed, or the old library version can be disabled or deleted if it is no longer needed.

    library multiple versions
    Figure 116. Multiple library versions
    • To install the same library multiple times, make sure to populate a unique library ID during installation to differentiate it from the previously installed instances. See Multiple Library Instances for more information.

    Multiple Library Instances

    Installing multiple instances of the same library can save you time if there is a need to handle the same data from multiple sources (e.g., when pulling the same data from different databases or different connection profiles), or when using the same data source but needing a way to limit the output based on user’s level of access (e.g., limit one group of users to see only a specific set of customer information).

    To provide an example of how to use multiple library instances, let’s take our Xero library, which can pull information from the Xero accounting system. Let’s assume your company has two branches, one in the United Kingdom and one in the United States. You want to make the data source connectors from the Xero library available for use in the Data Catalog in CloverDX Wrangler and want users to access data from their branch only.

    Installation and configuration steps
    • Install the Xero library twice with different library IDs (Xero_UK and Xero_US).

    libraries multiple install xero
    Figure 117. Multiple instances of Xero library
    • On the Configuration tab, configure each library instance with its OAuth2 connection, and tenant ID (consult the library documentation for the configuration steps). You can also set the date format based on the country (dd/MM/yyyy or MM/dd/yyyy).

    libraries xero uk config
    Figure 118. Configuration for UK branch
    libraries xero us config
    Figure 119. Configuration for US branch
    • Create new user accounts and two new user groups (in our case Accounting_UK and Accounting_US). Since these users will need access only to CloverDX Wrangler, the user groups are set up with only the default Wrangler permissions, i.e., Create sandbox and Access to the Wrangler UI.

    • On the Permissions tab set up the library-level permissions and the Data Source Connectors permissions for each library instance to be visible and available for use only to their respective user group.

    libraries xero uk permissions
    Figure 120. Permissions for UK branch
    libraries xero us permissions
    Figure 121. Permissions for US branch
    • Enable the library instances. After logging into CloverDX Wrangler, users will have access only to the data source connectors from their branch.

    libraries xero uk data catalog
    Figure 122. Wrangler Data catalog for UK branch
    libraries xero us data catalog
    Figure 123. Wrangler Data catalog for US branch

    Overview Tab

    The Overview tab displays basic information about the selected library and lists the public resources the library includes.

    library overview tab
    Figure 124. Library Overview tab
    Field Description

    Library name

    Library name displays the library name specified when exporting the project into a library, or the name that was entered in the Label field when installing the library. This is the name under which the library is available to all users (e.g., in the Scheduler or Event Listeners, or the Component Palette in the Designer). See Library Editing for more information on how to change a library name.

    Original name

    If a library name was changed during installation by specifying a custom Label, or if the original library name was changed by editing the library and modifying the Label, the original library name (as specified during library export), will be displayed next to the current library name. This will allow you to keep track of the original name.

    Library version

    Displays the library version specified during library export. Library versions are not editable.

    Library ID

    Library ID will be displayed when a different library ID was entered when installing the library.

    Library IDs can be used to install libraries multiple times. See Installation Logic for more information.


    Displays library description as specified during library export. Library descriptions are displayed when reviewing libraries in repositories or the list of installed libraries. Library descriptions can be changed. See Library Editing for more information.

    Sandbox code

    Displays the library sandbox name.


    Displays the username of the user who installed the library. Library owners have access to the Configuration and Permission tabs even when they are not granted the WRITE library-level permission. See Permissions Tab for more information.


    Displays the author of the library project as specified during library export.

    CloverDX version

    CloverDX version is automatically assigned based on the version of CloverDX Designer from which the library was exported.

    Last Modification Date

    Displays the date and time of library export from CloverDX Designer.

    Library-level Permissions

    Displays an overview of the library-level permissions on the Permissions Tab.

    Data Source Connectors, Subgraphs, Graphs, Jobflows, Rest Jobs, Metadata sections

    Lists the public library resources.

    Documentation Tab

    To add additional information that might be important to other users, or to keep track of changes in libraries, library documentation can be optionally added before exporting a project into a library. See exporting to library for more information on how a documentation page can be added.

    If a documentation file is present in a library, a Documentation tab will be displayed when displaying the library in a library repository and when reviewing the installed library detail in the Libraries section.

    library documentation tab
    Figure 125. Library Documentation tab

    Configuration Tab

    The Configuration tab is visible only to users assigned to a user group that has one of the following permissions combinations:

    Depending on the options selected during library export from CloverDX Designer, or depending on the library design, additional configuration steps might need to be performed after a library installation. Library configuration is performed in the Configuration tab. When reviewing the list of installed libraries, the following indicators related to library configuration might appear in a library record to easily identify what kind of configuration might need to be performed:

    Icon Description
    library bullseye icon

    Library has an initialization job.

    library wrench icon

    Library has configurable parameters.

    library plug icon

    Library has unauthorized OAuth2 connections.

    library unresolved dependencies icon

    Library has unresolved dependencies.

    Initialization Jobs

    If a library has an initialization job (see Initialization job usage), it is indicated by a bullseye icon.

    Figure 126. Library has an initialization job

    A library initialization job (a graph or jobflow) can be used after installation to CloverDX Server by server administrators. Users with the Libraries administration permission can run the initialization even when the library is disabled.

    The initialization job will come up in the Library Initialization section. You can run the job by clicking on the Initialize library button, even when the library is disabled. Note that you can use any other method for executing the initialization job (REST API, Simple HTTP API, etc.).

    Figure 127. Library initialization

    Configurable Parameters

    If a library includes configurable parameters (see exporting a library for more information), it is indicated by a wrench icon.

    Figure 128. Library has configurable parameters

    The supported parameter types are String, Secure String, Boolean, Integer, Decimal, and Enumeration. The parameter’s description is shown as an “i” icon with a tooltip.

    All such parameters are displayed in the Library Parameters section, where their values can also be populated.

    Note that to be able to modify values of secure parameters, users need to be assigned to a user group that has the Secure parameters administration permission enabled.

    If there is a parameter with an invalid value, the wrench icon will turn red to indicate that there is an issue and there will be an exclamation mark next to the affected parameter.

    libraryConfigurationParameters tooltip invalid values
    Figure 129. Library has parameter with invalid values
    Figure 130. Library parameters

    OAuth2 connections

    All implemented OAuth2 connections in a library appear on the Configuration tab, where they can be reviewed, updated, authorized, or re-authorized. Unused OAuth2 connections, i.e., connections present in a library project which are not used in any of the public or internal (sub)graphs, are not displayed.

    When exporting a library project, all OAuth2 connections are always exported as unauthorized even when they were authorized in CloverDX Designer during the development stage. After library installation, all used OAuth2 connections will need to be authorized again in CloverDX Server.

    If there is an unauthorized OAuth2 connection in a library, it is indicated by a red plug icon in the library list.

    library list oauth2 tooltip
    Figure 131. Library has unauthorized OAuth2 connection(s)

    Each OAUth2 connection appears in a separate section on the Configuration tab, and its title includes the filename of the related .cfg file, and the provider of the OAuth2 connection (e.g., Google, Azure, generic),

    All connections that need to be authorized have the Authorize button under them, and a note stating that the connection is not authorized. You can review and modify the connection properties if needed. If any of the connection properties are changed, the Authorize button becomes disabled until the changes are saved.

    library unauthorized oauth2
    Figure 132. Unauthorized connection

    By clicking on the Authorize button, you are redirected to the provider’s website to complete the authorization process. If the authorization process is successful, the button label changes to Re-authorize, and the note changes to indicate that the connection is authorized.

    library authorized oauth2
    Figure 133. Authorized connection


    If there is a dependency on another library, the Configuration tab will show the dependencies in the Dependencies section. If there is a dependent library missing, a red icon is displayed in the library list to indicate that there is an unresolved dependency, a warning is displayed in the Configuration tab, and the missing dependency is highlighted in the Dependency section.

    If the referenced library is installed under the same name, it is linked automatically; otherwise, you must resolve the dependency manually.

    After resolving dependencies manually, the dependency warning will automatically disappear but it is not possible to check if the dependency was resolved correctly until the library jobs or data source connectors are used. If a dependency is resolved incorrectly, the library jobs or data source connectors might fail even when there is no dependency warning.
    It is important to set the same library permissions on all the dependent libraries to ensure that library jobs or data connectors can run successfully. For more information see permissions.
    library dependencies
    Figure 134. Library has unresolved dependencies

    Permissions Tab

    On the Permissions tab, library-level permissions for libraries and data source connectors can be set. In combination with the permissions set at the user group level, it is possible to control library and data connector visibility and allowed operations in CloverDX Server, CloverDX Designer, and CloverDX Wrangler.

    Only users assigned to a user group that has one of the following permission combinations are allowed to view the Permissions tab:

    The tab includes two separate sections: one for library-level permissions that affect the visibility and allowed operations in CloverDX Server and CloverDX Designer, and one for data source connectors in the Data Catalog in CloverDX Wrangler if any are present in the given library.

    library permissions tab
    Figure 135. Permissions tab
    Any changes performed in the tab will be saved only after clicking on the Update permissions button.

    Library-Level Permissions

    The library-level permissions allow the following permissions to be set:

    • READ: controls if a user group can see the library in the list of libraries, and other places in CloverDX Server and CloverDX Designer.

    • WRITE: in combination with the Edit sandbox permission, controls if a user group can see the library Configuration and Permissions tabs, and edit information on these tabs.

    • EXECUTE: controls if a user group can execute graphs, subgraphs, jobflows, or data services from the public interface of the library.

    When there are library dependencies, it is important to set the same library permissions on all the dependent libraries to ensure that library jobs or data connectors can run successfully.

    Data Source Connector Permissions

    Data source connector permissions are set individually for each data connector by linking a user group to permission. To add a user group to permission, click in the column to activate the edit mode, and select the desired user group from the list. To remove a group, click on the X button on the right side of the group.

    library permissions edit
    Figure 136. Adding or removing user groups

    The data connector permissions allow the following permissions to be set:

    • VISIBLE IN DATA CATALOG: controls if a user group can see the data connector in the Data Catalog in CloverDX Wrangler. Users with only the READ permission will not be able to see data preview or add the connector to their sources.

    • USE IN WRANGLER: controls if a user group can add the data connector to their sources and use it Wrangler jobs.

    Data Source Connector Permissions Logic

    Users assigned to a user group that has the Unlimited access to sandboxes permission will be automatically granted all the library-level and data source connector permissions. For other user groups, it is important to set both the library-level permissions and data source connector permissions in the same way. This is because data connectors run on CloverDX Server to generate and display data on the Wrangler side. Having the same permissions for the libraries in which they are installed, and for the data connectors themselves, will ensure that the data connectors will be able to generate and display data successfully.

    To make the configuration easier, there is a check in place, which will display a warning if there is a discrepancy between the library-level and data source permissions. The warning will state which permissions and for which user groups will be ignored, and a warning icon will be displayed next to the group. The configuration can still be saved even when warnings are present; however, it is strongly recommended to correct the permission setup and remove all such warnings to ensure that the data source connector will run without an issue.

    When a library that includes data source connectors is dependent on other libraries, it is important to set the same library-level permissions on all the dependent libraries as well to ensure that the data source connectors can run successfully.
    library permissions warning
    Figure 137. Data source connector permissions warning

    Library Editing

    Click on the Edit button in the upper right corner of the Overview tab to access the Edit mode, which allows you to modify the Label (Library name) or Description of a library.

    Only users assigned to a user group that has one of the following permissions combinations are allowed to edit libraries:

    library edit tab
    Figure 138. Library editing

    Library Deleting

    To delete an installed library click on the library that should be removed and use the ⋮ menu on any of the tabs to display the Delete library option.

    Only users assigned to a user group that has one of the following permissions combinations are allowed to delete libraries:

    Library and Library Repository Configuration Exports

    Installed Library and Library Repository information can be easily exported in the CloverDX Server console under Configuration > Export.

    Library and Library Repository Configuration Import

    When you import Library or Library Repository configuration in the CloverDX Server console under Configuration > Import, CloverDX Server tries to find imported libraries in the list of installed libraries. If they are found they will be updated, otherwise, they will be installed from available repositories. Libraries are matched according to their original name, version, and library ID.