UIaaS API Programmers Guide

CloudHaven UI API Programmers Guide

API

Page Object | Component Object | Special Components

Client Script Functions

Communication | User Data | User Files | | Application Navigation | Notification | Messaging/Tasks/Workflow | Calendar

Overview

CloudHaven provides authentication, user management and a UI-as-a-Service (UIaaS). Vendors can register Applications or Components with CloudHaven. Registered Applications are then available in the “App Store”. A User may subscribe to an application in the App Store by clicking the “SUBSCRIBE” link for that application. Once subscribed that application will appear under “My Apps”. Clicking on an application under “My Apps” will launch that application. If it has one, the applications main menu will supersede the CloudHaven main menu available from the hamburger menu in the upper left of the main CloudHaven title bar.

Vendor Records

Currently there is no mechanism for vendors to self-register applications or components and this must be done by a CloudHaven administrator by editing a Vendor record. The Vendor record has the following fields:

1.       Name
Descriptive Name for the Vendor.

2.       Id
A hidden alphanumeric id with no spaces used as the programmatic identifier of this vendor.

3.       Components URL
The URL where this vendor’s components can be found. A POST handler should be registered at this URL which expects an object containing a “componentIds” member which is an array of component Ids as defined below under the Components Tab.

4.       Applications Tab
An application has the following fields:

a.       Name
Descriptive name of the application. Appears as the title of the App in the App Store or My Apps.

b.       Application Id
A hidden alphanumeric id with no spaces used as the programmatic identifier.

c.       URL
This the URL for the vendor’s backend server. This server should be configured to respond to the following http GETs and POSTs at this URL:

                                                               i.      Application Pages
Application pages are retrieved with http GETS from subpaths using the following convention: “/apppages/<page>”, where the first page accessed must be “home”. For example, the home page is then found at “/apppages/home” and if there was a page “secondpage” it would be found at “/apppages/secondpage”.

                                                             ii.      Other GETs and POSTS
The application may define any other GET and POST handlers as needed which can then be accessed via the CloudHaven client script “_appGet” and “_appPost” functions.

5.       Components Tab
This is where components are registered. It has the following fields:

a.       Name
A descriptive name for the component

b.       Id
The programmatic id used to by other applications that want to use the component to refer to that component.

API

An App “page”, accessed via the “/apppages/<page>” subpath (as described above under Vendor, Applications Tab, URL, Application Pages), is defined by the “Page” object.

Page Object

The page object contains all the information required to dynamically generate the page as well as customize the CloudHaven frame and main menu. The Page object contains the following properties (note that the properties, dataModel, methods, computed, filters are named the same as the corresponding options of Vue.component):

{
components: [
< array of component objects>],
externalComponents: [
<array of external component objects>],
requiredUserData:[
< Array of strings: array of user data ids to be pre-cached >],
dataModel: {
<dataModel object as would be returned by the Vue dataModel function>},
methods: {
<object specifying methods for this Vue “page” (see “methods” section below)},
computed: {
<object specifying “computeds” for this Vue “page” (see “computeds” section below)},
filters: {
<object specifying “filters” for this Vue “page” (see “filters” section below)},
watch: {
<object specifying “watches” for this Vue “page” (see “watches” section below)},
appFrame: {
name:
<String: Application Name>,
appBarStyle: {
<css styles>},
appBarTextClass:
<String: vuetify text class names>,
nameTextClass:
<String: vuetify text class names>,
menuItems: [
{page: “
<String: page name>”, title: “<String: title of page>”},

],
},
uiSchema: {
<object containing nested Vue/Vuetify component specifications
}

components

This property contains an array of “internal” component objects supplied by the vendor of this App (as opposed to “external” components which are supplied by other vendors. Component objects are the same as page objects except they may have a props property and do not have an appFrame property. See Component Objects below. Components are included in the UI using the “dynamicComponent” (see Special Components section).

externalComponents

This provides a mechanism for using components from other vendors that have been registered under the “Components” tab of their CloudHaven Vendor record. It takes an array of external component objects where that object has the following format:

{vendorId:”<vendor id value>”, componentId:”<component id value>”}

where <vendor id value> and <component id value> are valid ids defined in a Vendor record.

Like “internal” components above, external components are included in the UI using the “dynamicComponent” (see Special Components section).

requiredUserData

An array of strings, this specifies the ids of a user data item to be “pre-fetched” when the page is loaded (a performance optimization).

dataModel

This is an object containing all the elements of the data model, formatted identical to the object that would be returned by the dataModel function of a Vue component.

methods

The “methods” member of the page object is an object where the properties are method names and the value of those properties can be either a string containing the javascript body of that method or a “function” object containing the following properties:

{
args: [“arg1”, “arg2”, …],
//an array of function argument names as referenced in the body
body: “…” //a string containing the javascript for the body of the function
}
For example, the methods “currentDate” and “add” can be defined as:
methods: {
currentDate: “return new Date():”,
add: {
args:[“p1”, “p2”],
body:”return p1+p2;”
}
}

In functions defined as methods, computed, watch or filters, references to objects of the dataModel, computeds and methods must be prefaced with “this.” (same as for Vue). However, javascript used inline in component properties need not be prefaced with “this.” (again, same as for Vue).

The function body javascript is somewhat sandboxed in that it doesn’t allow references to the following objects or functions:

window, document, history, location, navigator, XMLHttpRequest, WebSocket, WindowOrWorkerGlobalScope, XMLDocument, ServiceWorkerContainer, Worker, localStorage

computed

This specifies the computed property of the Vue component options in the same manner as Vue except the functions are specified with a “function” object but with no args property (see methods section above). Note that a computed object can also be defined with an object containing get and set properties which in turn contain function objects for getting and setting the computed property respectively (same as for Vue component options).

filters

This specifies the filter property of the Vue component options in the same manner as Vue except the functions are specified with a “function” object (see methods section above).

watch

This specifies the watch property of the Vue component options in the same manner as Vue except the functions are specified with a “function” object (see methods section above).

appFrame

The appFrame property contains an object whose properties affect the CloudHaven “frame” when the App is started from My Apps, including the style of the title bar, the style of the title bar text, the style of the user’s name and the application main menu which replaces the CloudHaven main menu while the App is active.

uiSchema

This uiSchema object is the meat of the page containing a nested hierarchy of UI components including all properties, attributes, slots, events, etc. The component object definition closely parallels the Data Object parameter of the Vue createElement function – it also has the same class, style, attrs, props, domProps, on, nativeOn, scopedSlots, key and ref properties (however, there is no CloudHaven component equivalent for the directives, slot, and refInFor properties). UI Components include all Vuetify components, some CloudHaven-native components, and external and internal components defined with CloudHaven component objects.

Child components of a component are defined either in the “contents” property of a component (either as an array of components or a single component) or in the component’s scopedSlot property.

The component object closely mirrors a Vue component object with the exception that v-for directive is replaced with the “loop” property and the v-if/v-else/v-else-if directive family is replaced by the “show” and “omit” properties. Note that there is direct v-show equivalent, however the same effect can be done through manipulation of the display style.

The v-model directive is replaced with the component “vmodel” property.

Any v-on directives are implemented with the “on” property of the component (similar to the on property for the Vue.component data

There isn’t currently any CloudHaven equivalent for the following directives:

v-text
v-html
v-show
v-on (all event handlers are defined in the component “on” property)
v-bind (binding is handled by prefacing property names with the “:” character)
v-model (replaced with the “vmodel” property)
v-slot (all slots are defined in the component “scopedSlots” property)
v-pre
v-cloak
v-once

Component properties

·         component
This is the name of the component which references a “special component” (see below), a CloudHaven-native component or a vuretify component

The following CloudHaven-native components are currently available:

conversation (the CloudHaven, context-sensitive conversation component)
dateField (a text field where the text must be in a date format like MM/DD/YYYY)
fileViewer (for viewing text, pdf, image or docx files)

The following vuetify components are available:

alert (VAlert)
autocomplete (VAutocomplete)
avatar (VAvatar)
badge (VBadge)
banner (VBanner)
bottomNavigation (VBottomNavigation)
bottomSheet (VBottomSheet)
breadcrumbs (VBreadcrumbs)
col (VCol)
button (VBtn)
buttonToggle (VBtnToggle)
calendar (VCalendar)
calendarDaily (VCalendarDaily)
calendarMonthly (VCalendarMonthly)
calendarWeekly (VCalendarWeekly)
card (VCard)
cardSubtitle (VCardSubtitle)
cardTitle (VCardTitle)
cardText (VCardText)
cardActions (VCardActions)
carousel (VCarousel)
carouselItem (VCarouselItem)
chip (VChip)
chipGroup (VChipGroup)
checkbox (VCheckbox)
colorPicker (VColorPicker)
combobox (VCombobox)
container (VContainer)
dataIterator (VDataIterator)
dataFooter (VDataFooter)
datePicker (VDatePicker)
dataTable (VDataTable)
dataTableHeader (VDataTableHeader)
dialog (VDialog)
divider (VDivider)
expansionPanel (VExpansionPanel)
expansionPanelHeader (VExpansionPanelHeader)
expansionPanelContent (VExpansionPanelContent)
expansionPanels (VExpansionPanels)
editDialog (VEditDialog)
fileInput (VFileInput)
footer (VFooter)
form (VForm)
hover (VHover)
icon (VIcon)
image (VImg)
input (VInput)
item (VItem)
itemGroup (VItemGroup)
lazy (VLazy)
list (VList)
listGroup (VListGroup)
listItem (VListItem)
listItemAction (VListItemAction)
listItemActionText (VListItemActionText)
listItemAvatar (VListItemAvatar)
listItemContent (VListItemContent)
listItemGroup (VListItemGroup)
listItemIcon (VListItemIcon)
listItemSubtitle (VListItemSubtitle)
listItemTitle (VListItemTitle)
menu (VMenu)
navigationDrawer (VNavigationDrawer)
overflowButton (VOverflowBtn)
overlay (VOverlay)
pagination (VPagination)
parallax (VParallax)
progressCircular (VProgressCircular)
progressLinear (VProgressLinear)
overlay (VOverlay)
overlay (VOverlay)
radio (VRadio)
rangeSlider (VRangeSlider)
radioGroup (VRadioGroup)
rating (VRating)
responsive (VResponsive)
row (VRow)
select (VSelect)
sheet (VSheet)
simpleCheckbox (VSimpleCheckbox)
simpleTable (VSimpleTable)
skeletonLoader (VSkeletonLoader)
slider (VSlider)
slideGroup (VSlideGroup)
slideItem (VSlideItem)
snackbar (VSnackbar)
spacer (VSpacer)
sparkline (VSparkline)
stepper (VStepper)
stepperContent (VStepperContent)
stepperHeader (VStepperHeader)
stepperItems (VStepperItems)
stepperStep (VStepperStep)
subheader (VSubheader)
switch (VSwitch)
tab (VTab)
tabs (VTabs)
tabsItems (VTabsItems)
tabItem (VTabItem)
tabsSlider (VTabsSlider)
textarea (VTextarea)
textField (VTextField)
timePicker (VTimePicker)
timeline (VTimeline)
timelineItem (VTimelineItem)
toolbar (VToolbar)
toolbarTitle (VToolbarTitle)
toolbarItems (VToolbarItems)
tooltip (VTooltip)
treeview (VTreeview)
virtualScroll (VVirtualScroll)
window (VWindow)
windowItem (VWindowItem)

·         props
The “props” component property mimics the “props” property of the Vue createElement Data Object specifying the properties of the object. A props property takes a literal value, however, if the property name is prefaced with a “:” character the value is not taken literally but evaluated as an expression (dataModel objects, computed and methods in this expression do not need to be prefaced with “this.”).

For example:
{component:”textField”, props:{outlined: false, label:”First Name”}, vmodel:’formData.firstName’}

or

{component:”textField”, props:{outlined: false, “:label”:”firstNameLabel”}, vmodel:’formData.firstName’}
(where “firstNameLabel” is a property in the dataModel)

·         vmodel
This component property mimics the Vue v-model directive. The value of the vmodel property must be an object in the dataModel and does not need to be prefaced with “this.”

·         attrs
The “attrs” component property mimics the “attrs” property of the Vue createElement Data Object specifying the normal html attributes of the object (like “id”). An attrs property takes a literal value, however, if the property name is prefaced with a “:” character the value is not taken literally but evaluated as an expression (dataModel objects, computed and methods in this expression do not need to be prefaced with “this.”).

·         class
The “class” component property mimics the “class” property of the Vue createElement Data Object specifying the css classes for the object. A class property takes a literal value, however, if the property name is prefaced with a “:” character the value is not taken literally but evaluated as an expression (dataModel objects, computed and methods in this expression do not need to be prefaced with “this.”). As with the createElement Data Object class property, the class value can be a string, object, or array of strings and objects.

·         style
The “style” component property mimics the “style” property of the Vue createElement Data Object specifying the css style for the object. A style property takes a literal value, however, if the property name is prefaced with a “:” character the value is not taken literally but evaluated as an expression (dataModel objects, computed and methods in this expression do not need to be prefaced with “this.”). As with the createElement Data Object style property, the style value can be a string, object, or array of strings and objects.

·         domProps
The “domProps” component property mimics the “domProps” property of the Vue createElement Data Object specifying the DOM properties of the object (like “innerHtml”). A domProps property takes a literal value, however, if the property name is prefaced with a “:” character the value is not taken literally but evaluated as an expression (dataModel objects, computed and methods in this expression do not need to be prefaced with “this.”).

·         on, nativeOn
The “on” (and nativeOn) component property mimics the “on” (and nativeOn) property of the Vue createElement Data Object specifying the event handlers of the object (like “click”). The value of the “on” (or nativeOn) property is an object where each property of that object corresponds with an event of that object. Mimicking Vue, eventhandlers can have one or more of the following modifiers: ctrl, shift, alt, meta, stop, and prevent or the keycode modifiers sec, tab, enter, space, up, left, right, down or delete. For example:

{component:”button”, on:{‘click.stop’:”doButtonAction”}, …}

The value of a click handler can be one of the following:

string – then name of a method
function object
string expression (gets evaluated – does not require prefacing identifiers with “this.”

·         contents
The value of the “contents” component property can be any of the following:

o   A string
treated as the template contents for a “template” component or else treated as a text vnode for all other components

o   A CloudHaven component

o   An array of CloudHaven components or strings (the latter treated as text vnodes)

·         template
contains the text string template to be “template-compiled”. See the “template” special component below.

·         userData
This is used only for a subset of components that can contain User Data. The value specifies the User Data Id. This only applies to fields in the form component. The vmodel of these fields will be loaded with the value of User Data specified by this Id when the CloudHaven native function _getUserData is called. During an _appPost function call, the User Data associated with these fields will be stored in CloudHaven, the components values nulled out, the post done and then the user data values will be restored to these components (writes the data to CloudHaven, not to the vendor app)

·         scopedSlots
The value of the scopedSlots property contains an object where each of its properties references the name of a scopedSlot applicable to that component. The value of each scopedSlot is a component or array of components with the slot properties injected into the current scope. For example, given a datatable component with items defined by an array of objects containing a “firstName” property:

{component:”dataTable”, scopedSlots:{
item: {
component:”template”, template:”<tr><td>{{item.firstName}}</td></tr>”
}
}

 

Component Object

The Component Object is identical to the Page Object except it doesn’t have an “appFrame” property and can contains a “props” property the value of which is in a format that mimics the props of a Vue Component except that the type of a property is given as a String not an Object. For example, use

{type: “String”} instead of {type:String}

or

{type: “Object”} instead of {type: Object}

Special Components

template
The template component provides “html” template-compiled from the value in the “template” property. For example:

{component:”template”, template:”<span>{{someDataModelVar}}</span>”}

dynamicComponent
The dynamicComponent name references an internally (this vendor) or externally (different vendor) CloudHaven uiSchema-defined component. For example, the component with id “example-component”, which could be either an internal (this vendor) or external (different vendor) component would have a component specification that looked like:

{component: “dynamicComponent”, name: “example-component”}

loop

The loop component will iterate the array specified in the dataList property of this component, generating the component specified in the contents property while injecting the current dataList element of that iteration into the current scope.

Client Script Functions

Application Communication

_pdfGet( postId, cb)

Performs and http GET to the vendor backend (similar to _appGet) with a responseType of ‘blob’.

postId: this is a subpath that is appended to the application URL to make the target URL for this GET operation.

cb: This is an optional callback function that is executed after the GET operation responds. It expects one parameter which is the data portion of the response. It executes in the Vue scope for the current page (or component).

 

_appGet( postId, cb)

Performs and http GET to the vendor backend with the following headers:

Accept: ‘application/json’
Content-Type: ‘application/json’

postId: this is a subpath that is appended to the application URL to make the target URL for this GET operation.

cb: This is an optional callback function that is executed after the GET operation responds. It expects one parameter which is the data portion of the response. It executes in the Vue scope for the current page (or component).

 

_appGetFile( postId, fileId, cb)

Performs and http Get to the vendor backend at the subpath “/<postId>/<fileId>”. The has a “content-disposition” header with an “attachment” value containing the filename. The “content-type” header will indicate the MIME type of the returned file. The data is returned as a Blob.

postId: this is a subpath that is appended to the application URL to make the target URL for this GET operation.

fileId: this is the fileId to be used as defined by the application for retrieving the file from the vendor backend. It is appended at the end of the path to complete the HTTP GET URL.

cb: This is the callback function that executed after the GET operation responds. It expects one parameter which is the Blob containing the file data returned from the HTTP GET. It executes in the Vue scope for the current page (or component). The data passed to the callback can be used to create an object URL – for example, given the parameter is called “data” an object URL could be created as follows:

var objURL = URL.createObjectURL(data);


_appPost( postId, postData, cb)

Performs and http POST to the vendor backend with the following headers:

Accept: ‘application/json’
Content-Type: ‘application/json’

postId: this is a subpath that is appended to the application URL to make the target URL for this GET operation.

postData: the json object to be POSTed. If postData contains a “files” member the content type of the post will be “multipart/form-data” and postData will be treated as FormData object with “files.<filename>” properties append for each <filename> key in “files”.

cb: This is an optional callback function that is executed after the POST operation responds. It expects one parameter which is the data portion of the response. It executes in the Vue scope for the current page (or component).

 

User Data

_lookupCloudHavenUser( searchSpec, cb )

Searches for a CloudHaven user using a filter of the same format as the mongodb find operation filter.
searchSpec: The mongodb-style filter used to search for a CloudHaven user. The following fields are available to be searched:

email
firstName
middleName
lastName
dateOfBirth

cb: This is an optional callback function that is executed after the function completes. It expects one parameter which is the user record found or null if not match was found. It executes in the Vue scope for the current page (or component).

_userSearch( searchCriteria, cb )

Searches for a list of CloudHaven users given a search phrase in the searchCriteria parameter. It will find any user where the firstName, lastName or ssn contains that search phrase.

searchCriteria: a text phrase to be searched in the firstName, lastName or ssn fields of the user.

cb: This is an optional callback function that is executed after this function completes. It expects one parameter which is an array containing the users matching this searchCriteria. It executes in the Vue scope for the current page (or component).

 

_getUserData( userId,pTarget, pModelToUserDataMap, cb )

This function is used to “pre-fetch” specified user data. It will fetch any user data items whose ids are provided in any of the following:

·         requiredUserData property of the Page or Component object

·         userData property of a component

·         the pModelToUserDataMap parameter

Once fetched, the data will be stored in the data model of this page or component or in the object in the pTarget parameter if it is specified. Components with the userData property will be populated with the corresponding fetched data and/or properties defined by the pModelToUserDataMap will be populated.

userId: The internal CloudHaven (mongodb) id of the user.

pTarget: An optional alternate destination object for the data. If not specified, the destination object is the page or component data model.

pModelToUserDataMap: An optional parameter to specify additional user data items to retrieve along with the destination property to receive them.

cb: This is an optional callback function that is executed after this function completes. It executes in the Vue scope for the current page (or component).

 

_writeUserData( userId, pSource, pModelToUserDataMap, cb )

This function is used to write user data to the CloudHaven database. If the user record doesn’t exist it will be created.

userId: The internal CloudHaven (mongodb) id of the user.

pSource: An optional alternate source object for the data. If not specified, the source object is the page or component data model.

pModelToUserDataMap: specifies the mapping between the source object and the user data item ids.

cb: This is an optional callback function that is executed after this function completes. It executes in the Vue scope for the current page (or component).

 

_getUserDataForList( pUserIds, list, userIdField, fieldMap, cb )

This function is used to fetch user data for a list of users and populate an array (list) of objects. The assumption is that the list already has application data and it is being augmented with additional user data.

list: the list with existing application data, including a field containing the user id, which will receive the fetched user data.

userIdField: This is the field in the existing list containing the user id value which is used to match the user data retrieved.

fieldMap: this is a mapping from user data field to field of the objects in list

cb: This is an optional callback function that is executed after this function completes. It executes in the Vue scope for the current page (or component).

_getUserFile( userId, fileId, cb)

Fetches a User File for this userId and fileId from CloudHaven.

userId: the internal id of the user who is the owner of this file.

fileId: This is the internal Id of the file to be fetched.

cb: This is an optional callback function that is executed after the GET operation responds. It expects one parameter which is the file fetched. The data type of the file will be String for text or docx files (docx converted to html for display) and a File object for pdf or image files. The callback executes in the Vue scope for the current page (or component).


User Files

_getUserFile( userId, fileId, cb)

Fetches a User File for this userId and fileId from CloudHaven.

userId: the internal id of the user who is the owner of this file.

fileId: This is the internal Id of the file to be fetched.

cb: This is an optional callback function that is executed after the GET operation responds. It expects one parameter which is the file fetched. The data type of the file will be String for text or docx files (docx converted to html for display) and a File object for pdf or image files. The callback executes in the Vue scope for the current page (or component).

 

_userFileOperation( params, cb )

This function is add, update or delete a User File record. The parameters for this function are contained in the params parameter:

userId: The internal userId of the owner of the file record.

operation: valid operations are add, update or delete

userFileId: the internal Id of the User File record containing the file. Only supplied when updating or deleting.

name: The name of the file. This is the user-friendly descriptive name for the file that may differ from the fileName (typically is camel case and has no suffix, for example)

fileName: the filename of the file.

fileType: This parameter is required so that CloudHaven knows to treat the file as test or a binary Blob. If the mimeType is text or the docx mime type, the callback “cb” is called with a String parameter containing the file, otherwise it is a File object.

file: the contents of the file as a String for text or docx-type mimetypes otherwise a File object. Only required when operation is add or update.

cb: This is an optional callback function that is executed after this function completes. It executes in the Vue scope for the current page (or component). It will have one parameter indicating the success or failure of the operation.

 

 

Application Navigation

_gotoAppPage( page, appParams )

Applications use this function to navigate to a specific application page.

page: Specifies the page to navigate to. CloudHaven will make an http GET to the application URL with a subpath of “/apppages/<page>” and will expect a Page Object to be returned which it will use to dynamically generate the application page.

 

Notification

_showNotification( msg )

Displays the text in the “msg” parameter in the “notification” format in the notification area of the CloudHaven “title bar” at the top of the screen.

_showError( msg )

Displays the text in the “msg” parameter in the “error” format in the notification area of the CloudHaven “title bar” at the top of the screen.


Messaging/Tasks/Workflow

Unlike the old model of many separate stand alone applications that users have go to, login in to, and then navigate to a particular place in the app, CloudHaven brings that “place” directly to the user at the right time – application tasks (pages or components) can be…:

·         Placed in a User or Group Message/Task Queue

·         Established as a “Favorite”

·         Schedule in their calendar

_queueUserMessageOrTask( params, cb )

This function is used to send a message and/or queue a task on a user’s message queue. Messages in CloudHaven can have embedded vendor applications or components. Users’ Messages/Tasks can be segregated by Application, Component or Queue Type enabling users to easily filter their messages/tasks. Messages/Tasks are marked “read” after users view them. Note that Messages and Tasks can come from any registered vendor if the user has subscribed to the associated application or indicated they will accept components from that vendor.

Tasks can be configured to indicate completion and can have a separate completion message associated with the Task (see the function _setTaskCompletion) which users can review later.

Messages/Tasks can be sent to users or groups. If sent to a group AND optionally set to firstComeFirstServe, then the first person in the group to “grab” that message receives it and it is assigned to them and made inaccessible to others in the group.

Note that _queueUserMessageOrTask can be used simply to send a message to another user in which case only the username, subject, recipients and message parameters are used.

params can have the following properties:

usernames: an array of usernames (email) of users to receive the message/task. Either a username or a groupId may be specified.

group: a json object indicating the group to receive the message/task. Either a group or a username must be specified. It contains the following members

applicationId: the application or component the group applies to. The application “cloudhaven” indicates the group is a CloudHaven group, not a vendor application group.

groupId: the Id of the group

firstComeFirstServe: applies only if group specified, If Boolean true then it is removed from the group and assigned to a user when they “grab” it.

subject: a short subject synonymous with an email subject

message: The text message to send along with this task.

recipients: a json structure indicating who received this Message/Task for purposes of replying, forwarding or just for information. It contains the following members:

to: An array of usernames of users who received this message with the implication that it is sent to them for direct action (as opposed to cc’d or bcc’d which implies fyi). Tasks can only be sent to “to” recipients.

cc: An array of usernames of others who were copied on this message. Tasks cannot be sent to cc’d users

Note that there is no bcc counterpart here. Bcc’d users simply are listed in the array of usernames to which this Message/Task is sent and aren’t listed in either the to or cc properties above.

application: a json object specifying which application page or component to embed in the Message/Task

vendorId: The vendor id of the component or application page to be embedded in the Message/Task.

applicationId: The internal id of the application containing the page to be embedded in the Message/Task. Either an applicationId or a componentId must be specified.

componentId: The internal id of the component containing the page to be embedded in the Message/Task. Either an applicationId or a componentId must be specified.

appConfigData: An application defined json object containing information needed to by the embedded component or page (including info specifying the page if the embedded object is an application page instead of a component – it’s up to the application to “navigate” to that page).

 

schedule: a json object that indicates schedule for when this task or message to be delivered to the users Message(/Task) Queue. This will create a “Schedule Task” entry in this users calendar. At the delivery time this Scheduled Task will be marked delivered and placed in the users Message/Task Queue.

period: the periodicity of the delivery. Valid values are “Once”, “Daily”, “Weekly”, “Monthly” or “Yearly”

date: The date of a “Once” delivery, the start date for a periodic delivery or for a yearly delivery the month and day of this value determines the day of year of delivery.

hour: the hour of delivery (0-23)

minute: the minute of delivery (0-59)

dayOfWeek: if the period is Weekly, this defines which day of the week (0-6)

dayOfMonth: if the period is monthly, this defines which day of the month (1-31)

 

cb: This is an optional callback function that is executed after this function completes. It executes in the Vue scope for the current page (or component). It will have one parameter containing the internal id of the QueueItem created (which can be used to update or delete this QueueItem).

 

_setUserTaskDisposition( queueItemId, params, cb )

This function is used to indicate the disposition of the completed task. The embedded application page or component would call this function from client script when appropriate. It can be used to alter the Message/Task setting a “Result” message and/or indicating completion.

queueItemId: The internal Id of the CloudHaven Message/Task

params: has the following properties:

resultMessage: the text message to be set on the originating Message/Task

isDone: Set to Boolean true if the task was completed

cb: This is an optional callback function that is executed after this function completes. It executes in the Vue scope for the current page (or component). It will have one parameter indicating the success of the operation.

 

_deleteUserMessageOrTask( queueItemId, cb)

Use this function to later delete a User Message/Task created with _queueUserMessageOrTask. This will only succeed if the Message/Task has not already not been read or “grabbed”.

queueItemId: The internal Id of the CloudHaven Message/Task

cb: This is an optional callback function that is executed after this function completes. It executes in the Vue scope for the current page (or component). It will have one parameter indicating the success of the operation.

 

_createFavorite( params, cb )

This function is used to create a favorite link that navigates immediately and directly to a page of an application or a vendor component of any vendor application or component to which the user is subscribed. Favorites can only be created for the current user.

Name: a label for the favorite

application: a json object specifying which application page or component to which the favorite link references

vendorId: The vendor id of the component or application page to be embedded in the Message/Task.

applicationId: The internal id of the application containing the page to be embedded in the Message/Task. Either an applicationId or a componentId must be specified.

componentId: The internal id of the component containing the page to be embedded in the Message/Task. Either an applicationId or a componentId must be specified.

appConfigData: An application defined json object containing information needed to by the embedded component or page (including info specifying the page if the embedded object is an application page instead of a component – it’s up to the application to “navigate” to that page).

cb: This is an optional callback function that is executed after this function completes. It executes in the Vue scope for the current page (or component). It will have one parameter containing the internal id of the Favorite created (which can be used by the application/vendor to update this Favorite on behalf of the user).

 

Calendar

_addCalendarEntry( params, cb ) (preliminary/incomplete definition)

Adds an entry in the specified user’s or group’s calendar. Entries can be any of the following:

·         Event
(Informational)

·         Conference
(as an associated booked and scheduled voice or video conference)

·         Availability
(Covers holidays, different kinds of work hours, vacation, etc.

·         Reminder

·         Vendor/Application-defined
(the content could be a subscribed application or component)

params can have the following properties:

title: a descriptive title of this calendar entry.

usernames: an array of usernames (email ) of all the users for which the calendar entry is scheduled (typically is only a single username).

group: a json object indicating the group for which this calendar entry is scheduled. This calendar entry will appear on the calendar of all members of this group. Either a group or usernames must be specified. It contains the following members

applicationId: the application or component the group applies to. The application “cloudhaven” indicates the group is a CloudHaven group, not a vendor application group.

groupId: the Id of the group

calendarEntryType: valid values are “Event”, “Conference”, “Availability”, and “Reminder”

calendar: Specifies which calendar this entry will be created in. This is a json object with the following properties:

calendarId: the Id of the calendar. This may be one defined by the user or an application.

vendorId: the vendor of the application if one is specified

applicationId: if specifies then the calendarId is one for this application otherwise the calendarId specifies a user-defined calendar

content: the text, richtext or html content of this calendar entry.

attachments: file attachments

application: a json object specifying which application page or component will be used to create custom vendor-specific content for this calendar entry

vendorId: The vendor id of the component or application page to be embedded in the Message/Task.

applicationId: The internal id of the application containing the page to be embedded in the Message/Task. Either an applicationId or a componentId must be specified.

componentId: The internal id of the component containing the page to be embedded in the Message/Task. Either an applicationId or a componentId must be specified.

appConfigData: An application defined json object containing information needed to by the embedded component or page (including info specifying the page if the embedded object is an application page instead of a component – it’s up to the application to “navigate” to that page).

 

durationtype: valid values are “Hourly”, “All Day”, “Multi-day”

startdate: the date of the calendar entry or the start date if this is a multi-day entry

starttime: time this calendar entry starts. For multi-day entries, this would define the start time for each day.

enddate: Only applicable to multi-day calendar entries