1 | # Getting Started
|
2 |
|
3 | This SDK provides easier access to the [Dialog REST API (OpenApi)](https://dialog.hxgn-api.net/v0/openapi.yaml)
|
4 | which can be viewed with an [OpenApi Viewer/Editor](http://editor.swagger.io)
|
5 |
|
6 | ___
|
7 | Contents:
|
8 |
|
9 | - [Overview](#overview)
|
10 |
|
11 | - [Usage](#usage)
|
12 |
|
13 | - [First Steps](#first-steps)
|
14 |
|
15 | - [Workbenches & Workbench Actions](#workbenches-and-workbench-actions)
|
16 |
|
17 | - [Dialog Types](#types-of-dialogs)
|
18 |
|
19 | - [Views and Records](#views-and-records)
|
20 |
|
21 | - [Dialog Hierarchies](#dialog-hierarchies)
|
22 |
|
23 | - [Menus and Actions](#menus-and-actions)
|
24 |
|
25 | - [Offline](#offline)
|
26 | ___
|
27 |
|
28 | ## Installation
|
29 |
|
30 | Install `cv-dialog-sdk` using npm:
|
31 | ```bash
|
32 | npm install --save cv-dialog-sdk
|
33 | ```
|
34 | the package will install in the `package.json` under dependencies
|
35 |
|
36 | ## Overview
|
37 | ![Overview](./../SDK_Overview.png)
|
38 |
|
39 | ### The Catavolt Dialog Model
|
40 | 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
|
41 | significantly from traditional client/server architectures in that rather than targeting a specific resource (i.e.
|
42 | next page), the client simply asks the server to redirect it to the 'next' resource (often without knowing
|
43 | specifically what that resource will be).
|
44 |
|
45 | The **Dialog** abstraction itself, is a metaphor for a current channel of communication or more simply, a current
|
46 | resource. A **Dialog** contains information describing the UI itself, as well as any 'business data' that should be
|
47 | displayed. A **Redirection** is a pointer to the next **Dialog**. An **Action** is a submission or instruction to the
|
48 | server (to do 'something').
|
49 | A typical **Dialog** application flow is comprised of:
|
50 |
|
51 |
|
52 | 1) Asking the server for a **Redirection** to a **Dialog** (e.g. rendered as an Html Page)
|
53 |
|
54 | 2) Performing an **Action** on the **Dialog** (e.g. user clicks a link)
|
55 |
|
56 | 3) Receiving a **Redirection** to the next **Dialog** (e.g. resulting Page is shown)
|
57 |
|
58 |
|
59 | ## Usage
|
60 | 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).
|
61 | ```Javascript
|
62 | import { Catavolt, Log } from 'cv-dialog-sdk'; // pulls Catavolt and Log components
|
63 | ```
|
64 | ### First Steps
|
65 | The first server-client interaction with a Xalt app is **setting the tenant Id** and **Logging a user in** using the `cv-dialog-sdk`.
|
66 |
|
67 |
|
68 | The following occurs after the a tenantID is entered.
|
69 |
|
70 | #### Pre-Login call for tenant informationCall
|
71 | Prior to log in, The client needs to send some information in order to receive the tenant capabilities. First, The client makes the following call to receive the current tenant settings and capabilities after the client tenantID is set. This call returns a dictionary with information such as the languages the tenant has available for translation and the tenants ability to use the OAuth protocol:
|
72 |
|
73 |
|
74 | - call `Catavolt.getCapabilities:tenantID:apiKey`. This yields a `WSTenantCapabilityResult`:
|
75 |
|
76 | Call Parameters:
|
77 |
|
78 | Property Key | Type | Description
|
79 | --- | --- | ---
|
80 | tenantID | *String* | the tenant you are requesting the capabilities of
|
81 | apiKey | *String* | (optional) the tenant you are requesting the capabilities of
|
82 |
|
83 |
|
84 | WSTenantCapabilityResult Response:
|
85 |
|
86 | Property Key | Type | Description
|
87 | --- | --- | ---
|
88 | translationAvailable | *Boolean* | true/false if multiple languages are available
|
89 | availableLanguages | *Array* | if translationAvailable=true, this value will return a list of CodeRefs of available languages to choose from. If translationAvailable=false, this value will not be returned.
|
90 | defaultBrandingLoginJSON | *Dictionary* | the default login page branding JSON
|
91 | detectJailbrokenDevices | *Boolean* | true/false if the client should detect jailbroken devices
|
92 | mdmApiEnabled | *Boolean* | true/false if the tenant has enabled MDM
|
93 | oauthAuthorizationAvailable | *Boolean* | true/false if the tenant has enabled the OAUTH login path
|
94 | restApiEnabled | *Boolean* | true/false if the tenant has enabled the REST API
|
95 | savePasswordAllowed | *Boolean* | true/false if the tenant has enabled Save Password on mobile devices
|
96 | serverVersion | *String* | the current version of the cloud server.
|
97 |
|
98 | -->
|
99 |
|
100 | To login, the client must set the following device information:
|
101 |
|
102 | Property Key | Type | Description
|
103 | --- | --- | ---
|
104 | ClientVersion | *String* | The version of the client (iOS, Android)
|
105 | DisplayHeight | *Integer* | The height of the client screen/window
|
106 | DisplayWidth | *Integer* | The width of the client screen/window
|
107 | FormFactor | *String* | the form factor of the device size. Values: `small` is for phones. `medium` or `large` is for tablets.
|
108 | GPSSupported | *Boolean* | If the client supports GPS. Values: `true`, `false`
|
109 | platform | *String* | The client and device platform. *ex `android-react` or `ios-react`*
|
110 |
|
111 | - Set device properties
|
112 |
|
113 | * dynamic value *(value is a function)*
|
114 |
|
115 | ```javascript
|
116 | Catavolt.addDynamicDeviceProp(key, value);
|
117 | ```
|
118 |
|
119 | * static value *(value is a static, non-function type)*
|
120 | ```javascript
|
121 | Catavolt.addStaticDeviceProp(key, value);
|
122 | ```
|
123 |
|
124 | #### Login
|
125 | 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](https://support.catavolt.com/customer/login?return_to=%2Fcustomer%2Fen%2Fportal%2Farticles%2F1342497-extender-v3-user-guide---october-15-2018).
|
126 |
|
127 | On success, [Login](./interfaces/_models_login_.login.html) should create and pass back a [Session](./interfaces/_models_session_.session.html) (In the case of multi-factor authentication, it will present the proper authentication window [DialogRedirection](./interfaces/_models_dialogredirection_.dialogredirection.html) until it reaches the Session)
|
128 |
|
129 | * Basic Authentication
|
130 | ```javascript
|
131 | // Returns a promise
|
132 | Catavolt.login(
|
133 | tenantID,
|
134 | clientType,
|
135 | userID,
|
136 | password,
|
137 | ).then(session => {
|
138 | //Do any post login calls here
|
139 | });
|
140 | ```
|
141 | * oAuth
|
142 |
|
143 | 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)
|
144 |
|
145 | Use the following to get the oAuthUrl
|
146 | ```javascript
|
147 | const proofKey = await // acquire a random crypto security string method
|
148 | const initUrl = await CatavoltAuth.getOAuthUrl(tenantID, proofKey); // insert the tenantID and the generated proofKey
|
149 | ```
|
150 |
|
151 | At this point, you will need to display the URL and create an event listener to extract the callbackURL
|
152 | ```javascript
|
153 | Catavolt.loginWithToken(
|
154 | tenantID,
|
155 | clientType,
|
156 | permissionToken,
|
157 | proofKey,
|
158 | ).then(session => {
|
159 | //Do any post login calls here
|
160 | }); //returns a promise
|
161 | Catavolt.onSessionExpiration = pageController.logout;
|
162 | ```
|
163 |
|
164 |
|
165 |
|
166 |
|
167 |
|
168 | ### Workbenches and Workbench Actions
|
169 | A Dialog flow is initiated by performing a **WorkbenchAction**. A given user may have one or more **Workbench**es
|
170 | which may have one or more **WorkbenchAction**s. These provide entry points into the various application flows and can
|
171 | be thought of as initial 'Menus' with 'Menu Items'. Performing a **WorkbenchAction** will begin the **Dialog**
|
172 | application flow as described above.
|
173 |
|
174 | ### Types of Dialogs
|
175 | **Dialog**s will always be one of two subtypes:
|
176 | 1) An **EditorDialog**
|
177 | This type of **Dialog** is associated with one, single 'data record'
|
178 | E.g. Viewing the 'Details' of a single list item
|
179 | 2) A **QueryDialog** is associated with a list of 'data records'
|
180 | E.g. Viewing a tabular list or a map with location points
|
181 |
|
182 | ### Views and Records
|
183 | A **Dialog** is always associated with a **View** and one or more **Records**. **View**s represent various ways
|
184 | of displaying the 'data record(s)' to the user. **View**s themselves DO NOT contain the 'data record(s)',
|
185 | only information about how it
|
186 | should be displayed.
|
187 | Some types of Views are:
|
188 | 1) **Details** (Properties)
|
189 | 2) **List**
|
190 | 3) **Form** (Layout other Views)
|
191 | 4) **Map**
|
192 | 5) **Graph** (or chart)
|
193 |
|
194 | **Record**s contain the actual business data for display and may be combined with the display metadata provided by
|
195 | the **View**, to render the UI.
|
196 | * A single **Record** may be retrieved directly from an **EditorDialog**, following a **read()** operation.
|
197 | * Multiple **Records** may be retrieved as a **RecordSet** from a **QueryDialog** via the query() method.
|
198 | However, a **QueryScroller** may also be obtained from the **QueryDialog**, and provides a buffer with record
|
199 | pagining functionality.
|
200 |
|
201 | ### Dialog Hierarchies
|
202 | **Dialog**s may be composed of one or more 'child' **Dialog**s. This is typically used to layout a
|
203 | 'Form', such that the top-level is **Dialog** is an **EditorDialog** with a **Form** **View** . The **EditorDialog**
|
204 | will also have a list of 'child' **Dialog**s which will contain the **View**s to be arranged based on the **Form**
|
205 | **View**'s metadata.
|
206 | * When retrieving a new **Dialog** (i.e. following a **DialogRedirection**), the top-level **Dialog** will be an
|
207 | **EditorDialog** with a **Form** **View**
|
208 | * This **Dialog**'s 'child' **Dialogs** will typically be used to compose the UI (**Lists**, Details, Maps, etc.)
|
209 |
|
210 |
|
211 | ### Menus and Actions
|
212 | **View**s are associated with a **Menu**, which may in turn have a list of 'child' **Menu**s, enabling a hierarchical
|
213 | representation of nested menus and menu items. A **Menu** may also have an '**actionId**' which can be used to
|
214 | 'perform an Action' on the associated **Dialog**, typically resulting in the server returning a **Redirection** to
|
215 | another **Dialog** (i.e. resource, page, etc.)
|
216 | * **Actions** are used to transition from one **Dialog** to the next.
|
217 | * **actionId**s are simply strings but are typically retrieved from **Menu**s associated with a **View*````````*
|
218 |
|
219 | ### Documentation And Tools
|
220 | * **Dialog model** can be found [here](https://rawgit.com/catavolt-oss/cv-dialog-sdk/master/docs/dialog_model.pdf)
|
221 | * **(early) Api Docs** can be found [here](https://rawgit.com/catavolt-oss/cv-dialog-sdk/master/docs/cv-dialog-sdk/index.html)
|
222 |
|
223 | ### Offline
|
224 | Documentation coming soon
|
225 |
|
\ | No newline at end of file |