Building Experiences

You may choose to build your Experience using whatever means you wish, however there are some building tools available which may prove helpful, including:

• Cinchy SDK (Angular or Javascript)
• The ExecuteCQL endpoint
• The Saved Query endpoint
• Cinchy's API offerings

Cinchy SDK

If you choose to build in either angular or vanilla JS, there are SDKs that wrap the above methods to better interact with the Cinchy platform. To use the SDK methods, you need to:

• Install the package
• Import the Cinchy library
• Configure the SDK
• Review the included methods

Cinchy Angular SDK

The Cinchy Angular SDK package can be found here.

Install

To install the SDK library:

1. As an admin, open a terminal from within your angular project directory.
2. Run one of the following installation codes, depending on the version of Cinchy and Angular used by your project:

Angular Version	Cinchy Version	SDK Version	Install Code
5 or under	4.0.0 or under	1.x.x	npm install @cinchy-co/angular-sdk@1.0.0 --save
6, 7, or 8	2.x.x	2.x.x	npm install @cinchy-co/angular-sdk@2.x.x --save
6, 7, or 8	3.x.x	3.x.x	npm install @cinchy-co/angular-sdk@3.x.x --save
6, 7, or 8	4.0.0 to 4.5.x	4.0.0	npm install @cinchy-co/angular-sdk@4.0.0 --save
6, 7, or 8	4.6.0 or above	4.1.0	npm install @cinchy-co/angular-sdk@4.1.0 --save
6, 7, 8, or 9	4.15.1 or above	4.2.0	npm install @cinchy-co/angular-sdk@4.2.0 --save
7, 8, 9, or 10	4.15.1 or above	4.4.0	npm install @cinchy-co/angular-sdk@4.4.0 --save
12 or above	4.15.1 or above	5.1.4	npm install @cinchy-co/angular-sdk --save

info

Note: In order to use the .getUserPreferences() and .getTranslatedLiterals functions in the API (SDK versions 4.0.0+), your Cinchy version should be at least on Cinchy v4.x.x.

Import

To import the Cinchy Library:

1. Open your AngularAppModule.
2. Run the following command:

// Import Cinchy's module and service
import { CinchyModule } from '@cinchy-co/angular-sdk';

@NgModule({
  ...
  imports: [
    ...
    // Import CinchyModule in imports
    CinchyModule.forRoot()
  ],

  // Add CinchyModule as one of the providers
  providers: [CinchyModule],
  ...
})
export class AppModule { }

Configure

Once the CinchyModule is imported as per the above steps, you can use the library via CinchyService anywhere you can inject into.

Prior to making an API call to Cinchy, you must configure CinchyService and log in to the Cinchy platform.

The example below shows how to do this in AppComponent.

// Import CinchyService to make API calls and CinchyConfig to configure the service
import { CinchyService, CinchyConfig } from '@cinchy-co/angular-sdk';
...

// Create a config (as a class of CinchyConfig) to be loaded into CinchyService
export const MyCinchyAppConfig: CinchyConfig = {
  // The root url of your Cinchy instance
  cinchyRootUrl: 'http://my.cinchy.instance.co',
  // The url of your Cinchy IdentityServer
  authority: 'http://my.cinchy.instance.co/cinchyssocore',
  // The redirect url after logging in
  redirectUri: 'http://my-app-url/',
  // The client id for your applet
  clientId: 'my-applet-id',
  // (Optional) The redirect url after you logout
  logoutRedirectUri: 'http://localhost:3000/',
  // (Optional) The requested scopes for the applet (must be permitted for the client)
  // You must have openid and id requested
  scope: 'openid id email profile roles',
  // (Optional) Enable silent refresh
  silentRefreshEnabled: true,
  // (Optional) (Mandatory if silentRefreshEnabled = true) The silent refresh url
  silentRefreshRedirectUri: 'http://localhost:3000/silent-refresh.html'
};

@Component({
  ...
  // Load the MyCinchyAppConfig into CinchyService
  providers: [CinchyService, {
    provide: CinchyConfig, useValue: MyCinchyAppConfig
  }]
  ...
})

export class AppComponent {

  // Inject CinchyService into this component
  constructor(private _cinchyService: CinchyService) {

    // Redirect to login screen
    this._cinchyService.login().then( response => {
        console.log('Login Success!');
    }).catch( error => {
        console.log('Login Failed');
    });
  }

Using the Angular SDK (Functions)

You can review the Angular SDK Functions here.

Using the Angular SDK (Examples)

The below example shows how you might execute a query and parse the returned data using the Angular SDK.

const data = [];
const domain = 'My Domain Name';
const query = 'My Query Name';

// Values such as connectionid, transactionid, and parameterized variables in the query
const params = {'@city': 'Toronto'};

this._cinchyService.executeQuery(domain, query, params).subscribe(
    response => {
        let queryResult = response.queryResult;
        // Parses the result data
        while (queryResult.moveToNextRow()) {
            const this_row = {};
            for (const col of queryResult.getColNames()){
                this_row[col] = queryResult.getCellValue(col);
            }
            data.push(this_row);
        }

        // Printing the result after parsing
        console.log(data);
    },
    error => {
        console.log(error);
    });

The following example shows how you might execute a custom query and parse the returned data using the Angular SDK.

// CSQL Query
const query = 'SELECT * FROM [DOMAIN].[TABLE NAME]';

// Values such as connectionid, transactionid, and parameterized variables in the query
const params = null;

const data = [];
this._cinchyService.executeCsql(query, params).subscribe(
    response => {
        let queryResult = response.QueryResult;
        // Parses the result data
        while (queryResult.moveToNextRow()) {
            const this_row = {};
            for (const col of queryResult.getColNames()){
                this_row[col] = queryResult.getCellValue(col);
            }
            data.push(this_row);
        }

        // Printing the result after parsing
        console.log(data);
    },
    error => {
        console.log(error);
    });

Cinchy Javascript SDK

The Cinchy Javascript SDK package can be found here.

Install and Import

To install the SDK library:

1. Navigate to the Javascript SDK repo.
2. Under "Tags", click on the SDK version that corresponds to your Cinchy version. The version you download should match the following table.

Cinchy Version	SDK Version
4.6.0+	4.1.0
4.0.0 - 4.5.x	4.0.0
2.x.x - 4.4.x	2.x.x
Under 2.x.x	1.x.x

3. Download the SDK package and insert it into your codebase.
4. Include the cinchy.js script in any html pages that use the SDK. For example:
   <script src="js/cinchy.js"></script>

Configure

To connect to Cinchy, you must configure the window's cinchyJS object in your Javascript code. For example:

window.cinchyJS = new CinchyJS({
    // The url of your Cinchy instance
    cinchyRootUrl: 'http://my.cinchy.url.co',
    // The identity server of your Cinchy instance
    authority: 'http://my.cinchy.url.co/cinchyssocore',
    // The client id for your applet
    client_id: 'javascript-sample',
    // (Optional) The requested scopes for the applet (must be permitted for the client)
    // You must have openid and id requested
    scope: 'openid id email profile roles',
    // (Optional) Enable silent refresh
    silent_refresh_enabled: true,
    // (Optional) (Mandatory if silentRefreshEnabled = true) The silent refresh url
    silent_redirect_uri: 'http://localhost:3000/silent-refresh.html',
    // The callback function that gets executed after login
    user_loaded_callback: initialize
});

Using the Javascript SDK (Functions)

The Javascript SDK functions can be found in the cinchy.js project file.

---

ExecuteCQL Endpoint

The ExecuteCQL endpoint is used to execute a Cinchy Query Language function directly, without creating a Saved Query.

This is achieved using a POST request, which can be utilized when building your application experience.

Further details on the ExecuteCQL endpoint can be found here.

---

Saved Query Endpoint

All Saved Queries in Cinchy are automatically available as REST APIs, and can be called and executed using the Saved Query endpoint.

This is achieved using a GET request, which can be utilized when building your application experience.

Further details on the Saved Query endpoint can be found here

Cinchy APIs

Cinchy offers a range of APIs that can be leveraged for your application experience use cases.

A full list of current API offerings and how to use them can be found here.

Appendix A - Angular SDK Capabilities

There are some extra capabilities available to be leveraged in your App when building using the Cinchy Angular SDK, such as:

• Silent Refresh
• Embedding
• Translate API

These are detailed in the sections below.

Silent Refresh

You can choose to optionally configure your app to utilize the silent refresh capability, which automatically refreshes your access token every 75% of your token's lifetime.

Silent refresh works by using a hidden iframe to access a url that contains the silent-refresh.html page. This iframe makes a request to the server to retrieve a new access token.

caution

Note that the Cinchy SDK Silent Refresh capability is not available if using a PAT. Token refresh will need to be managed by the app builder instead.

To enable silent refresh:

1. Navigate to your CinchyConfig object > silentRefreshEnabled property.
2. Set the property to true.
3. Add a silent-refresh.html file anywhere in your Angular project. You can find this in the /src/lib/ folder in the SDK repo, or you can copy and paste the below into a new file:

<html>
    <body>
        <script>
            parent.postMessage(location.hash, location.origin);
        </script>
    </body>
</html>

4. Navigate to your angular.json file > assets property.
5. Specify the silent-refresh.html path and file, for example "src/silent-refresh.html":

"assets": [
    "src/favicon.ico",
    "src/assets",
    "src/silent-refresh.html"
],

6. In your Cinchy platform, navigate to the [Cinchy].[Integrated Clients] table.
7. Add the silent-refresh url to the Permitted Login Redirect URLs column.
   1. eg: MyApp.com/silent-refresh.html

Embedding

Your app can be embedded and launched within the Cinchy platform itself.

info

Please note that in order for iFrame to properly resize within the Cinchy platform, the height of your outer most elements (a div container for example) needs to have a style height of auto.

Prior to embedding, you must use the iframe-resizer library in your Angular App. This will allow your app to be properly resized within an iFrame when integrated into the Cinchy UI.

The iframe-resizer package is included in the Cinchy npm package by default. It is installed within your node_modules directory. To configure your App to use this capability:

1. Navigate to your .angular.json file.
2. Insert the iframe-resizer.json files into your project's scripts:

"scripts": [
    "../node_modules/iframe-resizer/js/iframeResizer.min.js",
    "../node_modules/iframe-resizer/js/iframeResizer.contentWindow.min.js"
],

Translate API

Multilingual support is available through the [Cinchy].[Literals] and [Cinchy].[Literal Translations] tables, and these can be accessed via an API POST request inside of your app.

To use the Translation API in your app, you will call the getTranslatedLiterals(guids) function and use the returned dictionary to bind the translated text into your app view.

Before doing so, you must add your literals and literal translations into your Cinchy platform. You can find more information about these steps here

After setting up your Literals:

1. As an admin, open a new terminal and run the below command to import the CinchyLiteralDictionary:

import { CinchyLiteralDictionary } from '@cinchy-co/angular-sdk';

2. Navigate to the [Cinchy].[Literals] table.
3. Copy the GUID(s) associated with whichever string(s) you want to translate in your app.
4. Insert the GUID(s) as an array inside of your app component and initialize a CinchyLiteralDictionary object. For example:

export class AppComponent {
  literalDictionary: CinchyLiteralDictionary;
  guids: string[] = ["27d4314b-adee-4e89-ad7f-2381a21729cf",
  "67c7dab0-9a7d-4ec9-88d0-271700c779b4",
  "47d9840d-0e09-4693-ae52-c726c5927a3a"];

5. Bind the GUID(s) to your component's view. For example:

<div *ngIf="literalDictionary">
    <h1>{{ literalDictionary['27d4314b-adee-4e89-ad7f-2381a21729cf'].translation }}</h1>
    <p>Translation 1: {{ literalDictionary['67c7dab0-9a7d-4ec9-88d0-271700c779b4'].translation }}!</p>
    <p>Translation 2: {{ literalDictionary['47d9840d-0e09-4693-ae52-c726c5927a3a'].translation }}!</p>
</div>

6. Make the API call by passing in the GUID(s) into the getTranslatedLiterals(guids) formula, and setting the dictionary that you initialized in the previous step as the response. For example:

export class AppComponent {
    literalDictionary: CinchyLiteralDictionary;
    guids: string[] = ["27d4314b-adee-4e89-ad7f-2381a21729cf",
    "67c7dab0-9a7d-4ec9-88d0-271700c779b4",
    "47d9840d-0e09-4693-ae52-c726c5927a3a"];

    constructor(private _cinchyService: CinchyService) {
        var _this = this;
        this._cinchyService.login().then(function() {
        _this._cinchyService.getTranslatedLiterals(_this.guids).subscribe(
                resp => {
                    _this.literalDictionary = resp;
                },
                error => {
                    console.log('Error getting translations: ', error);
                }
            );
        });
    }
}

Appendix B - Javascript SDK Silent Refresh

You can choose to optionally configure your app to utilize the silent refresh capability, which automatically refreshes your access token every 75% of your token's lifetime.

Silent refresh works by using a hidden iframe to access a url that contains the silent-refresh.html page. This iframe makes a request to the server to retrieve a new access token.

caution

Note that the Cinchy SDK Silent Refresh capability is not available if using a PAT. Token refresh will need to be managed by the app builder instead.

1. Navigate to rou CinchyJS object.
2. Set the silent_refresh_enabled property to true
3. Add a silent-refresh.html file anywhere in your project. You can do so by:
   1. Copy and pasting the silent-refresh.html file from the Javascript SDK repo.
   2. Copy and pasting the below code into your project, modifying the script src location to match where you cinchy.js file is:

<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
    <title></title>
</head>
<body>
    <script src="/js/cinchy.js"></script>
    <script>
        new Oidc.UserManager().signinSilentCallback().catch((err) => {
            console.log(err);
        });
    </script>
</body>
</html>

3. In your Cinchy platform, navigate to the [Cinchy].[Integrated Clients] table.
4. Add the silent-refresh url to the Permitted Login Redirect URLs column. eg: MyApp.com/silent-refresh.html