Skip to main content

Using CinchyDXD

Overview​

This section covers everything you need to export a release package from a data experience.

Prerequisites​

Define the data experience​

You must define your data experience in the Data Experience Definitions Table. Each row in the table is a definition for each Data Experience you want to package and export.

A definition contains the entities that make up the experience. Some examples of entities are tables, domains, reference data, and user defined functions (UDFs) .

For a complete list of all fields, see the Data Experience Definitions reference page.

Best practices​

Cinchy recommends packaging entities based on their dependencies on one another. For example entities such as Applets, System Colours, Literal Groups, and Models can be packaged separately. This makes versioning these entities easier when exporting to other environments.

Updating data experiences​

If you make changes to the DX in the future, update the relevant Data Experience definition. You don't need to create a new definition. If you need to review what the definition looked like historically, you can view it via the Collaboration log.

Define the reference data​

For each table data reference, you must define an entry in the Data Experience Reference Data system table. This entry will be deployed alongside your Data Experience Definition (DX).

Treat this reference data similarly to a Data Sync Configuration for batch synchronization. It should move data from a CSV file to a Cinchy Table with matching attributes. The sync key column should contain unique values and shouldn't be a system or calculated column.

For a complete list of all columns, please see the Data Experience Reference Table.

Export the data experience​

After you define the data experience and the reference data you want with it, you can now use PowerShell to export your experience.

info

You must have PowerShell 7 or later to use CinchyDXD

To export your data experience:

  1. Launch PowerShell and navigate to your CinchyDXD folder (such asC:\DxDvX.X.X)
  2. Run .\CinchyDXD.ps1 export with the required and optional parameters.

Export arguments​

Use the arguments below to create your data export with CinchyDXD.

ParameterDescriptionRequirement
exportExports a Data Experience from a Cinchy source environment.Required.
-u (Username)User ID for accessing Cinchy. Required when not using a Personal Access Token.Optional
-p (Password)Clear text password or Personal Access Token. If using a token, do not provide -u.Required
-g (DXD Guid)The Data Experience Definition Guid.Required
-v (DXD Version)The Data Experience Definition Version.Required
-o (DXD Output Directory)Path where CinchyDXD will create the Data Experience release export.Required
-k (Encryption Key File)Path to the encryption key file for encrypting metadata.Optional
-w (Write Binary Files to Cinchy)Flag to save release files into Cinchy.Optional
-x (CinchyDXD Temp Directory)Flag to prevent cleanup of the output temp directory.Optional
-start (Start Step)Export Step to start from.Optional
-end (End Step)Export Step to end on.Optional

Example​

The following example shows the use of arguments for a data package export in Cinchy.

.\CinchyDXD.ps1 export -s "sandbox.cinchy.net/source-url-environment" -u "JohnDoe" -p "123456" -d "C:\Logs\CLI-Output-Logs -g "d98a1f18-f4bf-8695-ef04ghfa47" -v "1.0.0" -o "C:\CinchyDXDOutput"

Validate export process​

To validate your export, navigate to the target output path and make sure it's populated with the necessary files.

Export failures list​

Error: Release already exists​

The export will fail if a record with the same Name, GUID, and Version already exists in the Data Experience Releases system table in the lower environment.

Solutions:​
  1. Update package version: Required if the Data Experience definition has been modified since the last installed version in the higher environment.
  2. Delete the release: Required if the version isn't yet installed in the higher environment.

Error: References to deleted metadata​

This error indicates that Data Experience Definitions are pointing to a deleted entity (such as a saved query in the Recycle Bin).

Solution:​

Manually update the definition to remove the reference to the deleted data.

Install the Package​

After exporting your data package, install it into the target environment.

  1. Run the install command using the parameters outlined in the below table. Note: These parameters are for DXD 1.7. For the list of parameters used in other versions, please reference the Commands page.
 `.\CinchyDXD.ps1 install`
OptionDescriptionRequirement
-s (Cinchy Server )The full path to the Cinchy server without the protocol (e.g. cinchy.com/Cinchy).Required
-u (Username)The user id for accessing Cinchy.Required
-pThe clear text password of the username provided.Required
-dPath to a directory for storing temporary Connection files.Optional
-e (Pause on Errors)Prompt to continue on Connection and Model Loader errors.Optional
-m (Ignore Model Errors)Do not stop on Model Loader errors.Optional
-z (Display Sync Output)Display Connections output on completion.Optional
-k (Encryption Key File)Path to the encryption key file for metadata decryption. It's essential to use the same key file that was used during the generation of the package by DXD Export.Optional
-skip (Skip Sync)Comma delimited list of Tables and/or Table.Column(s) to skip when the sync for a table is performed.Optional
-start (Start Step)The Install Step to start from.Optional
-end (End Step)The Install Step to end on.Optional
-y (Force Install)Force install if release already exists in the target.Optional

Example​

.\CinchyDXD.ps1 install -s "sandbox.cinchy.net/target-url-environment" -u "JohnDoe" -p "123456" -d "C:\Logs\CLI-Output-Logs"
  1. Validate the install by:
    1. Making sure that all entities that were present were installed on the target environment. For example, make sure your tables, data sync configurations, and saved queries are present.
    2. Making sure that the Data Experience Definitions table has the DX parameters from the source environment.

Appendix A​

List of Actions​

For a list of actions and parameters execute one of the following at the PowerShell command prompts:

  • .\CinchyDXD version
  • .\CinchyDXD help
  • .\CinchyDXD export
  • .\CinchyDXD install
  • .\CinchyDXD keygen

Encrypting files​

  1. Run the below command, where TargetDirectory is your desired output path.
.\CinchyDXD.ps1 keygen -o "<TargetDirectory>"
  1. Find the dxd.key file created.