BDS Script Functions

The Business Data Storage (BDS) provides a set of functions that can be used inside FNZ Studio Solutions.

Synchronization Algorithm

BDSSyncAllDataClasses

This function triggers a full run of the Synchronization Algorithm that parses all the Data Classes currently stored with the BDS, and aligns the Data Class configuration with the Database model according to the latest version of each Data Class.

The main use case for this function is to automate deployment through staging environments. For example, when moving a set of stored Data Classes from a Development environment to a Production environment, you can invoke this function from a deployment script to align the Database model as well.

The function may return a text containing all the issues found during the execution of the Synchronization Algorithm.

Inputs None

Outputs (String) A description of the issues found while synchronizing all the Data Classes stored with the BDS; null if no issue was found.

BDSCleanupAndSyncAllDataClasses

This function cleans up the Data Class configuration and syncs all the Data Classes stored with the BDS again. The cleanup removes all the associations of the Data Classes with Database tables and columns (but it maintains the configured Cascade Modes), therefore it allows the FNZ Studio developer to start over with a brand new set of tables and columns.

All the Database tables associated with the Data Classes stored in the BDS must not exist in the Database. If at least one table is found, the operation is aborted and an exception is thrown.

Inputs None

Outputs (String) A description of the issues found while synchronizing all the Data Classes stored with the BDS after their cleanup; null if no issue was found.

CRUD Operations

BDSSaveDataClassInstance

This function saves the given Data Class instance in the Database. If it was never saved before, it inserts it; otherwise it updates it. It also updates the provided instance by adding or updating its Persistence ID.

The cascade and cleanupCollectionMode parameters can optionally be provided to control how the Data Class instance is saved. When cascade is true, the Persistence ID is also added or updated in the Data Class instances found inside the properties being cascaded.

Saving a Data Class instance may result in the deletion of the given instance or of other ones according to the defined property cascade modes.

For more details on the behavior of the Save operation, see the BDS Operations article.

Inputs

  • (Any) dataClassInstance: the Data Class instance to be saved.
  • (Boolean, Optional) cascade: if true, cascades the Save operation to the properties with cascade mode Cascade Save or higher. If false, only the provided object is saved. Default is false.
  • (String, Optional) cleanupCollectionMode: cleans up collections by removing null values before the given Data Class instance is persisted. Default is none, available options are:
    • none: does not remove any null value from collections
    • indexed: removes all null values from all Indexed Collections
    • named: removes all null values from all Named Collections
    • all: removes all null values from all collections
    • missingTargetIndexed: removes all null values caused by deleted target objects from all Indexed Collections of property type CCV
    • missingTargetNamed: removes all null values caused by deleted target objects from all Named Collections of property type CCV
    • missingTargetAll: removes all null values caused by deleted target objects from all collections of property type CCV

Outputs (Long) Persistence ID of the saved Data Class instance.

BDSSaveDataClassInstances

This function saves the given Data Class instances in the Database. If a Data Class instance was never saved before, it inserts it; otherwise, it updates it. It also updates the provided instances by adding or updating their Persistence IDs.

The cascade and cleanupCollectionMode parameters can optionally be provided to control how the Data Class instances are saved. When cascade is true, the Persistence ID is also added or updated in the Data Class instances found inside the properties being cascaded.

Saving a Data Class instance may result in the deletion of the given instances or of other ones according to the defined property cascade modes.

For more details on the behavior of the Save operation, see the BDS Operations article.

Inputs

  • (Indexed Any) dataClassInstances: the Data Class instances to be saved.
  • (Boolean, Optional) cascade: if true, cascades the Save operation to the properties with cascade mode Cascade Save or higher. If false, only the provided objects are saved. Default is false.
  • (String, Optional) cleanupCollectionMode: cleans up collections by removing null values before the given Data Class instances are persisted. Default is none, available options are:
    • none: does not remove any null value from collections
    • indexed: removes all null values from all Indexed Collections
    • named: removes all null values from all Named Collections
    • all: removes all null values from all collections
    • missingTargetIndexed: removes all null values caused by deleted target objects from all Indexed Collections of property type CCV
    • missingTargetNamed: removes all null values caused by deleted target objects from all Named Collections of property type CCV
    • missingTargetAll: removes all null values caused by deleted target objects from all collections of property type CCV

Outputs (Indexed Long) Persistence IDs of the saved Data Class instances.

BDSDeleteDataClassInstance

This function deletes the Data Class instance with the given type and Persistence ID from the Database

The cascade parameter can optionally be provided to control how the Data Class instance is deleted.

For more details on the behavior of the Delete operation, see the BDS Operations article.

Inputs

  • (DataClass:Reference) dataClassReference: the type of the Data Class instance to be deleted (e.g. DataClass:NewReference('COB:Client')).
  • (Long) persistenceId: the Persistence ID of the Data Class instance to be deleted.
  • (Boolean, Optional) cascade: if true, it cascades the Delete operation to the properties with cascade mode Cascade Delete. If false, only the provided object is deleted. Default is false.

Outputs Nothing

BDSDeleteDataClassInstances

This function deletes the Data Class instances with the given type and Persistence IDs from the Database.

The cascade parameter can optionally be provided to control how the Data Class instances are deleted.

For more details on the behavior of the Delete operation, see the BDS Operations article.

Inputs

  • (DataClass:Reference) dataClassReference: the type of the Data Class instances to be deleted (e.g. DataClass:NewReference('COB:Client')).
  • (Indexed Long) persistenceIds: the Persistence IDs of the Data Class instances to be deleted.
  • (Boolean, Optional) cascade: if true, it cascades the Delete operation to the properties with cascade mode Cascade Delete. If false, only the provided objects are deleted. Default is false.

Outputs Nothing

BDSLoadDataClassInstance

This function loads the Data Class instance of the given type and Persistence ID from the Database. The cascade and cleanupCollectionMode parameters can optionally be provided to control how the Data Class instance is loaded.

For more details on the behavior of the Load operation, see the BDS Operations article.

Inputs

  • (DataClass:Reference) dataClassReference: the type of the Data Class instance to be loaded (e.g. DataClass:NewReference('COB:Client')).
  • (Long) persistenceId: the Persistence ID of the Data Class instance to be loaded.
  • (Boolean, Optional) cascade: if true, it cascades the Load operation to the properties with cascade mode Cascade Load or higher. If false, only the provided object is loaded. Default is false.
  • (String, Optional) cleanupCollectionMode: cleans up collections by removing null values. Default is none, available options are:
    • none: does not remove any null value from collections
    • indexed: removes all null values from all Indexed Collections
    • named: removes all null values from all Named Collections
    • all: removes all null values from all collections
    • missingTargetIndexed: removes all null values caused by missing target objects from all Indexed Collections of property type CCV
    • missingTargetNamed: removes all null values caused by missing target objects from all Named Collections of property type CCV
    • missingTargetAll: removes all null values caused by missing target objects from all collections of property type CCV

Outputs (Any) Loaded Data Class instance or null if not found.

BDSLoadDataClassInstances

This function loads the Data Class instances of the given type and Persistence IDs from the Database.

The function returns a mapping of each Persistence ID and the corresponding loaded Data Class instance. The Persistence IDs of the Data Class instances that have not been found are not mapped.

The cascade and cleanupCollectionMode parameters can optionally be provided to control how the Data Class instances are loaded.

For more details on the behavior of the Load operation, see the BDS Operations article.

Inputs

  • (DataClass:Reference) dataClassReference: the type of the Data Class instances to be loaded (e.g. DataClass:NewReference('COB:Client')).
  • (Indexed Long) persistenceIds: the Persistence IDs of the Data Class instances to be loaded. The collection must not be empty.
  • (Boolean, Optional) cascade: if true, it cascades the Load operation to the properties with cascade mode Cascade Load or higher. If false, only the provided objects are loaded. Default is false.
  • (String, Optional) cleanupCollectionMode: cleans up collections by removing null values. Default is none, available options are:
    • none: does not remove any null value from collections
    • indexed: removes all null values from all Indexed Collections
    • named: removes all null values from all Named Collections
    • all: removes all null values from all collections
    • missingTargetIndexed: removes all null values caused by missing target objects from all Indexed Collections of property type CCV
    • missingTargetNamed: removes all null values caused by missing target objects from all Named Collections of property type CCV
    • missingTargetAll: removes all null values caused by missing target objects from all collections of property type CCV

Outputs (Named Any) Mapping between each of the given Persistence IDs and the loaded Data Class instance retrieved from the Database.

BDSFindDataClassInstances

This function loads the Data Class instances of the given type from the Database by using the Persistence IDs returned by the given SQL query. Dynamic parameters can optionally be provided to be used in the SQL query.

The cascade and cleanupCollectionMode parameters can optionally be provided to control how Data Class instances are loaded.

For more details on the Load operation behavior, see the BDS Operations article.

Inputs

  • (DataClass:Reference) dataClassReference: the type of the Data Class instances to be loaded (e.g. DataClass:NewReference('COB:Client')).
  • (String) query: SQL query that returns the Persistence IDs to be loaded e.g. SELECT persistence_id FROM ' & BDSGetMainTableName(DataClass:NewReference('COB:Client')) & ' WHERE name LIKE '%Joe%.
  • (Indexed Any, Optional) queryParameters: SQL query parameters. If parameters have different types (e.g. one String parameter and one Integer parameter), it uses an Indexed Any collection object.
  • (Boolean, Optional) cascade: if true, it cascades the Load operation to the properties with cascade mode Cascade Load or higher. If false, only the selected objects are loaded. Default is false.
  • (String, Optional) cleanupCollectionMode: cleans up collections by removing null values. Default is none, available options are:
    • none: does not remove any null value from collections
    • indexed: removes all null values from all Indexed Collections
    • named: removes all null values from all Named Collections
    • all: removes all null values from all collections
    • missingTargetIndexed: removes all null values caused by missing target objects from all Indexed Collections of property type CCV
    • missingTargetNamed: removes all null values caused by missing target objects from all Named Collections of property type CCV
    • missingTargetAll: removes all null values caused by missing target objects from all collections of property type CCV

Outputs (Indexed Any) List of Data Class instances retrieved from the Database.

CRUD Utilities

BDSGetPersistenceId

This function returns the Persistence ID of the given Data Class instance.

Inputs (Any) dataClassInstance: the Data Class instance whose Persistence ID should be returned.

Outputs (Long) Persistence ID of the given Data Class instance if found; null otherwise.

BDSRemovePersistenceId

This function removes the Persistence ID from the given Data Class instance and returns the same Data Class instance for your convenience.

Optionally, it recursively deletes the Persistence ID from all the Data Class instances found in the properties of the given Data Class instance.

Inputs

  • (Any) dataClassInstance: the Data Class instance whose Persistence ID should be removed.
  • (Boolean, Optional) recurse: if true, it recursively deletes the Persistence ID from all the Data Class instances found in the properties of the given Data Class instance. Default is false.

Outputs (Any) Data Class instance without Persistence ID.

BDSIsDataPlaceholder

This function returns true if the given path points at a DataPlaceholder created by the BDS; false otherwise. It throws an exception if one or more nodes in the path are DataPlaceholders themselves (excluded the leaf node).

Inputs (Any) dataPath: the location to be checked, for example: $entity.propertyName

Outputs (Boolean) true if the given path points at a DataPlaceholder created by the BDS; false otherwise.

BDSLoadDataPlaceholderContent

This function replaces the property value pointed by the given path by reading the DataPlaceholder present in the property value, if any DataPlaceholder is present and if it was created by the BDS.

If the value pointed by the DataPlaceholder is a single Data Class instance and it is not found in the Database, null is set. If the value pointed by the DataPlaceholder is an Indexed or Named value and an entry is not found in the Database, null is set for that entry.

It throws an exception if one or more nodes in the path are DataPlaceholders themselves (excluded the leaf node).

Inputs

  • (Any) dataPath: the path of the DataPlaceholder to be loaded, for example: $entity.propertyName.
  • (Boolean, Optional) cascade: If true, it cascades the Load operation to the loaded Data Class instance properties with cascade mode Cascade Load or higher. If false, only the selected Data Class instances are loaded. Default is false.
  • (String, Optional) cleanupCollectionMode: cleans up collections of the loaded Data Class instances by removing null values. Default is none, available options are:
    • none: does not remove any null value from the collections
    • indexed: removes all null values from all Indexed Collections
    • named: removes all null values from all Named Collections
    • all: removes all null values from all collections
    • missingTargetIndexed: removes all null values caused by missing target objects from all Indexed Collections of property type CCV
    • missingTargetNamed: removes all null values caused by missing target objects from all Named Collections of property type CCV
    • missingTargetAll: removes all null values caused by missing target objects from all collections of property type CCV

Outputs (Boolean) true if the DataPlaceholder was loaded; false otherwise.

BDSRemoveDataPlaceholders

This function removes DataPlaceholders from the given Data Class instance by setting null in place of a DataPlaceholder, and it returns the same Data Class instance for convenience. Optionally, it recursively deletes DataPlaceholders from all the Data Class instances found in the properties of the given Data Class instance.

Inputs

  • (Any) dataClassInstance: the Data Class instance from which the DataPlaceholders must be removed.
  • (Boolean, Optional) recurse: If true, it recursively deletes the DataPlaceholders from all the Data Class instances found in the properties of the given Data Class instance. Default is false.

Outputs (Any) The given Data Class instance without the DataPlaceholders.

CRUD Transactions

BDSOpenConnection

This function opens a new connection towards the Data Source configured for the BDS.

Note that auto-commit is set to false. You are strongly recommended to wrap the script language code that follows this script in a try-catch to ensure that both the BDSRollbackTransaction and the BDSCloseConnection functions are called in case an exception occurs.

Inputs None

Outputs Nothing

BDSCommitTransaction

This function commits the SQL operations executed on a connection created by using the BDSOpenConnection function.

Inputs None

Outputs Nothing

BDSRollbackTransaction

This function rolls back the SQL operations executed on a connection created by using the BDSOpenConnection function.

Inputs None

Outputs Nothing

BDSCloseConnection

This function closes a connection created by using the BDSOpenConnection function. Closing a connection without previously calling either the BDSCommitTransaction or the BDSRollbackTransaction function explicitly may result in a rollback or in a commit of the executed SQL statements, according to the implementation of the specific driver being used. Therefore, you are strongly recommended to commit/roll back the statements before closing the connection to ensure a deterministic behavior.

Inputs None

Outputs Nothing

Name Resolver

BDSGetMainTableName

This function returns the name of the main table associated with the given Data Class. The table name is returned in the format <schema_name>.<table_name> where <schema_name> is the name of the Database schema specified in the Data Source used by the BDS.

Inputs (DataClass:Reference) dataClassReference: the Data Class for which the main table name should be returned (e.g. DataClass:NewReference('COB:Client')).

Outputs (String) The name of the main table associated with the given Data Class in the format <schema_name>.<table_name>.

BDSGetColumnName

This function returns the name of the Database column associated with the given Simple Value (SV) property on the main table of the given Data Class. The property type must be a simple value supported by the BDS.

Inputs

  • (DataClass:Reference) dataClassReference: the Data Class for which the column name should be returned. (e.g. DataClass:NewReference('COB:Client')).
  • (String) propertyName: the name of the SV property for which the column name should be returned.

Outputs (String) The name of the column associated with the given SV property on the main table of the given Data Class.

BDSGetCollectionTableName

This function returns the name of the collection table associated with the given Collection of Simple Values (CSV) property of the given Data Class. The property type must be a collection of simple values whose type is supported by the BDS. The table name is returned in the format <schema_name>.<table_name> where <schema_name> is the name of the Database schema specified in the Data Source used by the BDS.

Inputs

  • (DataClass:Reference) dataClassReference: the Data Class for which the collection table name should be returned (e.g. DataClass:NewReference('Misc:Address')).
  • (String) propertyName: the name of the CSV property for which the collection table name should be returned.

Outputs (String) The name of the collection table associated with the given CSV property of the given Data Class in the format <schema_name>.<table_name>.

BDSGetForeignKeyColumnNames

This function returns the name of the two columns associated with the given Complex Value (CV) property on the main table of the given Data Class. The property type must be a complex value whose type is stored in the BDS.

Inputs

  • (DataClass:Reference) dataClassReference: the Data Class for which the two column names should be returned (e.g. DataClass:NewReference('COB:Client')).
  • (String) propertyName: the name of the CV property for which the two column names should be returned.

Outputs (Indexed String) The name of the columns associated with the given CV property on the main table of the given Data Class. The first item in the returned collection is the name of the column containing the persistence ID of the Data Class instance that is the target of the relationship, while the second item is the name of the column that contains the name of the table where the target Data Class instance is located.

BDSGetBridgeTableName

This function returns the name of the bridge table associated with the given Collection of Complex Values (CCV) property of the given Data Class. The property type must be a collection of complex values whose type is stored in the BDS. The table name is returned in the format <schema_name>.<table_name> where <schema_name> is the name of the Database schema specified in the Data Source used by the BDS.

Inputs

  • (DataClass:Reference) dataClassReference: the Data Class for which the bridge table name should be returned (e.g. DataClass:NewReference('COB:Client')).
  • (String) propertyName: the name of the CCV property for which the bridge table name should be returned.

Outputs (String) The name of the bridge table associated with the given CCV property of the given Data Class in the format <schema_name>.<table_name>.