Skip to main content

Package the data experience

Overview​

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

Prerequisites​

Before you start, make sure you have access to the following tables:

  1. Data Experience Definitions Table
  2. Data Experience Reference Data Table

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.

export Required. Exports a Data Experience from a Cinchy source environment.
-s (Cinchy Server) Required. The full path to the Cinchy server without the protocol (e.g. cinchy.com/Cinchy) 
-u (Username) Optional. The User ID for accessing Cinchy. Username is required when not using a Personal Access Token. 
-p (Password) Required. The clear text password of the Username provided, or a Personal Access Token. If using a Personal Access Token, do not provide -u (Username) 
-g (DXD Guid) Required. The Data Experience Definition Guid. 
-v (DXD Version) Required. The Data Experience Definition Version. 
-o (DXD Output Directory) Required. The path to a directory where CinchyDXD will create the Data Experience release export.
-k (Encryption Key File) Optional. This is the path to the encryption key file. The key file is used when encrypting the metadata generated by DXD Export. It is important to note that the same key file needs to be used during package installation.
-w (Write Binary Files to Cinchy) Optional. Flag indicating that CinchyDXD should save the release files into Cinchy. This argument is deprecated in DXD 2.0.
-x (CinchyDXD Temp Directory) Optional. Flag indicating that CinchyDXD should not clean up the output temp directory.
-start (Start Step) Optional. The Export Step to start from.
-end (End Step) Optional. The Export Step to end on.

For a list of the available parameters, see the Export section of the CinchyDXD commands reference page for more information.

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.

Next steps​