Getting Started

This SDK provides easier access to the Dialog REST API (OpenApi) which can be viewed with an OpenApi Viewer/Editor

Contents:

Overview
Usage
First Steps
Workbenches & Workbench Actions
Dialog Types
Views and Records
Dialog Hierarchies
Menus and Actions
Offline

Installation

Install cv-dialog-sdk using npm:

npm install --save cv-dialog-sdk

the package will install in the package.json under dependencies

Overview

The Catavolt Dialog Model

The Catavolt Dialog Model represents an 'Abstract User Interface', managed by the server, transposed via the Dialog Service, and delivered to the cv-dialog-sdk. This SDK contains the instruction set for rendering the client's UI. This system differs subtly, but significantly from traditional client/server architectures in that rather than targeting a specific resource (i.e. next page), the client simply asks the server to redirect it to the 'next' resource (often without knowing specifically what that resource will be).

The Dialog abstraction itself, is a metaphor for a current channel of communication or more simply, a current resource. A Dialog contains information describing the UI itself, as well as any 'business data' that should be displayed. A Redirection is a pointer to the next Dialog. An Action is a submission or instruction to the server (to do 'something').
A typical Dialog application flow is comprised of:

1) Asking the server for a Redirection to a Dialog (e.g. rendered as an Html Page)

2) Performing an Action on the Dialog (e.g. user clicks a link)

3) Receiving a Redirection to the next Dialog (e.g. resulting Page is shown)

Usage

To use the SDK, first include the objects you wish to pull into your project (this example pulls in the main Catavolt object and the Log. see the API for all components).

import { Catavolt, Log } from 'cv-dialog-sdk'; // pulls Catavolt and Log components

First Steps

The first server-client interaction with a Xalt app is setting the tenant Id and Logging a user in using the cv-dialog-sdk.

To login, the client must set the following device information:

Property Key	Type	Description
ClientVersion	String	The version of the client (iOS, Android)
DisplayHeight	Integer	The height of the client screen/window
DisplayWidth	Integer	The width of the client screen/window
FormFactor	String	the form factor of the device size. Values: `small` is for phones. `medium` or `large` is for tablets.
GPSSupported	Boolean	If the client supports GPS. Values: `true`, `false`
platform	String	The client and device platform. ex `android-react` or `ios-react`

Set device properties
- dynamic value (value is a function)
```
Catavolt.addDynamicDeviceProp(key, value);
```
- static value (value is a static, non-function type)
```
Catavolt.addStaticDeviceProp(key, value);
```

There are two ways to log into the Xalt Framework, Basic Authentication and OAuth. If you have OAuth present in your system and need assistance integrating it to Catavolt Extender take a look at the Catavolt User Guide.

On success, Login should create and pass back a Session (In the case of multi-factor authentication, it will present the proper authentication window DialogRedirection until it reaches the Session)

Basic Authentication

// Returns a promise
Catavolt.login(
  tenantID,
  clientType,
  userID,
  password,
).then(session => {
  //Do any post login calls here
});

oAuth

oAuth requires native platform rendering and display of the browser window for loading the oAuthUrl that is set in Xalt Extender (see the Catavolt User Guide linked above). Along with the oAuthUrl, you will also need to generate a proof key. The proofKey will be passed along with the oAuth call in order to prevent man in the middle attacks on the login token issuance. (a strong crypto string with at least 16 characters is recommended)

Use the following to get the oAuthUrl
```
  const proofKey = await // acquire a random crypto security string method
  const initUrl = await CatavoltAuth.getOAuthUrl(tenantID, proofKey); // insert the tenantID and the generated proofKey
```
At this point, you will need to display the URL and create an event listener to extract the callbackURL
```
  Catavolt.loginWithToken(
  tenantID,
  clientType,
  permissionToken,
  proofKey,
  ).then(session => {
  //Do any post login calls here
  }); //returns a promise
  Catavolt.onSessionExpiration = pageController.logout;
```

Workbenches and Workbench Actions

A Dialog flow is initiated by performing a WorkbenchAction. A given user may have one or more Workbenches which may have one or more WorkbenchActions. These provide entry points into the various application flows and can be thought of as initial 'Menus' with 'Menu Items'. Performing a WorkbenchAction will begin the Dialog application flow as described above.

Types of Dialogs

Dialogs will always be one of two subtypes:
1) An EditorDialog
This type of Dialog is associated with one, single 'data record'
E.g. Viewing the 'Details' of a single list item
2) A QueryDialog is associated with a list of 'data records'
E.g. Viewing a tabular list or a map with location points

Views and Records

A Dialog is always associated with a View and one or more Records. Views represent various ways of displaying the 'data record(s)' to the user. Views themselves DO NOT contain the 'data record(s)', only information about how it should be displayed.
Some types of Views are: 1) Details (Properties) 2) List 3) Form (Layout other Views) 4) Map 5) Graph (or chart)

Records contain the actual business data for display and may be combined with the display metadata provided by the View, to render the UI.

A single Record may be retrieved directly from an EditorDialog, following a read() operation.
Multiple Records may be retrieved as a RecordSet from a QueryDialog via the query() method. However, a QueryScroller may also be obtained from the QueryDialog, and provides a buffer with record pagining functionality.

Dialog Hierarchies

Dialogs may be composed of one or more 'child' Dialogs. This is typically used to layout a 'Form', such that the top-level is Dialog is an EditorDialog with a Form View . The EditorDialog will also have a list of 'child' Dialogs which will contain the Views to be arranged based on the Form View's metadata.

When retrieving a new Dialog (i.e. following a DialogRedirection), the top-level Dialog will be an EditorDialog with a Form View
This Dialog's 'child' Dialogs will typically be used to compose the UI (Lists, Details, Maps, etc.)

Menus and Actions

Views are associated with a Menu, which may in turn have a list of 'child' Menus, enabling a hierarchical representation of nested menus and menu items. A Menu may also have an 'actionId' which can be used to 'perform an Action' on the associated Dialog, typically resulting in the server returning a Redirection to another Dialog (i.e. resource, page, etc.)

Actions are used to transition from one Dialog to the next.
actionIds are simply strings but are typically retrieved from Menus associated with a *View*

Documentation And Tools

Dialog model can be found here
(early) Api Docs can be found here

Offline

Documentation coming soon