Exploring available data

Tip

If your application does not provide functionality to browse available sites, channels, topics and tags then you can skip this chapter and move onto receiving real time data for tag references directly, as discussed in the next chapter.

Get available sites

UaolCloud.fetchSitesAsync()

Query the cloud service for available sites.

Returns:Promise – Returns an array of Site objects.
UaolCloud.getSites()

Get sites previously fetched.

Returns:Array.<Site> – Sites
UaolCloud.getSiteCount()

Get the number of sites previously fetched.

Returns:number – Number of sites

Example:

1
2
3
4
5
6
7
8
9
function getSites() {
    UaolCloud.getSitesAsync().then((sites) => {
        var numSites = sites.length;
        console.log('getSites successful, number of sites: ' + numSites)
    })
    .catch((error) => {
        console.error(error);
    });
}

Query site for available channels

Site Class

class Site()

Use the Site object to gain access to the site’s channels.

Site.getName()

Get the site name. If the site is end-to-end encrypted (see isEncrypted) then the name returned may be different from the name that is revealed once the site access key is set.

Returns:string – The site name
Site.fetchChannelsAsync()

Query the site for available channels

Returns:Promise – Returns an object in the form {site: Site, channels: Array.<Channel>}.
Site.getChannels()

Get the channels previously fetched.

Returns:Array.<Channel> – Array of channels
Site.getChannelCount()

Get the number of channels previously fetched.

Returns:number – Number of channels
Site.isEncrypted()

Indicates whether the site is end-to-end encrypted. If the site is end-to-end encrypted then the user needs to be prompted for the access key that must then be set before querying the site further.

Returns:boolean – True if the site uses end-to-end encryption, False otherwise
Site.isAccessible()

Indicates whether the site can be accessed or whether an access key is required. A site that is not end-to-end encrypted is accessible without an access key. If the site is not accessible then the user needs to be prompted for the access key that must then be set before querying the site further.

Returns:boolean – False if the site is encrypted and no access key has been set, True otherwise
Site.setAccessKeyAsync(accessKey)

Set the access key for an end-to-end encrypted site. The access key is never sent to the cloud service. Note that the Site’s getName method may return a different result after the access key has successfully been set, depending on the site’s configuration.

Arguments:
  • accessKey (string) – Access key provided by the administrator of the UA Office Link site.
Returns:

Promise – Returns the Site object

Examples:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
function setSiteAccessKey(site, key) {
    site.setAccessKeyAsync(key).then((site) => {
        console.log('Set access key OK for ' + site.getName());
    })
    .catch((error) => {
        console.error(error);
    });
}

function getChannels(site) {
    site.fetchChannelsAsync().then((result) => {
        var numChannels = result.channels.length;
        console.log('getChannels successful, number of channels: ' + numChannels)
    })
    .catch((error) => {
        console.error(error);
    });
}

Query channel for available topics

Channel Class

class Channel()

Use the Channel object to gain access to the channel’s topics.

Channel.getName()

Get the channel name. If the site is end-to-end encrypted (see isEncrypted) then the name returned may be different from the name that is revealed once the site access key is set.

Returns:string – The channel name
Channel.fetchTopicsAsync()

Query the cloud service for available topics for this site.

Returns:Promise – Returns an object in the form {site: Site, topics: Array.<Topics>}.
Channel.getTopics()

Get the topics previously fetched.

Returns:Array.<Topic> – Array of topics
Channel.getTopicCount()

Get the number of topics previously fetched.

Returns:number – Number of topics
Channel.getSite()

Get the site that contains the channel

Returns:Site – The channel’s site

Examples:

1
2
3
4
5
6
7
8
9
function getTopics(channel) {
    channel.fetchTopicsAsync().then((result) => {
        var numTopics = result.topics.length;
        console.log('getTopics successful, number of topics: ' + numTopics)
    })
    .catch((error) => {
        console.error(error);
    });
}

Query topic for available tags

Topic Class

class Topic()

Use the Topic object to gain access to the topic’s tags.

Topic.getName()

Get the topic name

Returns:string – The topic name
Topic.fetchTagsAsync()

Query the cloud service for available tags for this topic.

Returns:Promise – The result of the promise is an object in the form {topic: Topic, tags: Array.<Tag>}.
Topic.getTags()

Get tags previously fetched.

Returns:Array.<Tag> – Tags
Topic.getTagCount()

Get the number of tags previously fetched.

Returns:number – Number of tags
Topic.getChannel()

Get the channel that contains the topic

Returns:Channel – The topic’s channel

Example:

1
2
3
4
5
6
7
8
9
function getTags(topic) {
    topic.fetchTagsAsync().then((result) => {
        var numTags = result.tags.length;
        console.log('getTags successful, number of tags: ' + numTags)
    })
    .catch((error) => {
        console.error(error);
    });
}

Tag Class

class Tag()

Use the Tag object to gain access to real-time data.

Tag.getName()

Get the tag name

Returns:string – The tag name
Tag.getId()

Get a numerical tag identifier that is unique for this session only. This identifier is used in updateLiveValues callbacks.

Returns:number – The tag identifier
Tag.getTopic()

Get the topic that contains the tag

Returns:Topic – The tag’s topic
Tag.getReference()

Get a persistent tag reference. Tag objects can be re-created from a persistent tag reference.

Returns:string – The persistent tag reference
Tag.fromReferenceAsync(tagReferences, siteAccessKeys)

Static function to create one or more Tag object(s) from one or more tag reference(s)

Arguments:
  • tagReferences (string|Array.<string>) – A single tag reference or an array of tag references
  • siteAccessKeys (object|Array.<object>) – Optional. One or more access key name/value pairs for end-to-end encrypted sites, for example: {name: ‘Site1’, value: ‘secret’}
Returns:

Promise – Returns an array of tags.

Example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
function resolveTagRefs(tagRefs) {
    // passing access key for 'Headquarters' site
    UaolCloud.Tag.fromReferenceAsync(
        tagRefs,
        [{name: 'Headquarters', value: 'secret'}]
    ).then ((tags) => {
        // success
    })
    .catch((error) => {
        console.error(error);
    });
}