Complete Example

In the following sections we explore a typical use case where UA Office Link is collecting data on-premise with some data being sent into the cloud for access in our new Web application. We know what data is available in advance and design a Web page to present that data in a useful format.

Sign In

After deciding which data you would like to present you can use the UA Office Link Cloud API to integrate real-time data into your Web page. To retrieve the data, you first need to pass tag references to the cloud service via the API. Although the API provides functionality to explore available tags and tag references, the easiest option is to sign in at https://cloud.uaofficelink.com to select and copy tag references interactively. These references can then simply be pasted into your your own Javascript.

You will need a valid UA Office Link subscription to sign into the UA Office Link Cloud Web site. Use your subscription user name and password to sign in at https://cloud.uaofficelink.com (this will go through the auth.uaofficelink.com site to prompt for credentials).

../../../_images/signin.png

Browse available tags

Once you are signed in you will be presented with available sites. If there are no data sources sending data into the cloud then you may notice a message near the top of the browser window informing you that there are no sites available. Use your on-premise UA Office Link application to start your cloud transfer task first or call your on-site administrator to do it for you.

After the on-premise task has started sending data into the cloud press the Refresh button to retry.

../../../_images/nosites.png

Your site should now be available. In this example the site is called ‘Auckland Production Machinery’. If you are authorized to access more than one site then you may see multiple site names listed. Drill down to channels by clicking or tapping on a site name or on the arrow icon on the far right.

../../../_images/sites.png

Click or tap a channel name or the arrow icon on the far right to view channel topics.

../../../_images/channels.png

Drill down to tags by clicking or tapping on a topic name or on the arrow icon on the far right.

../../../_images/topics.png

You can select one or all tags by clicking on the check mark on the left. Note that you can also select tags for multiple topics or tags for multiple sites by checking topics or sites at a higher level.

../../../_images/checktags.png

Copy tag references

Click on the ‘Copy Tag References’ button to copy tag references for use in your own Web page. Tag references are copied as a comma-separated list of strings for use in a Javascript array. If you keep the ‘Include plaint text tag description’ box ticked then the human readable site, channel, topic and tag name is appended for each tag reference as a Javascript comment.

../../../_images/copytagrefs.png

Copied tag references may look like this, for example:

'AsjkYmnsopHs6msy0lKsuLkfdfOwplAs0BbFn7LEQg8AAAACAAACaJGb', // Auckland Production Machinery, Channel1, Machine1, Random.Int2
'AsjkYmnsopHs6msy0lKsuLkfdfOwplAs0BbFn7LEQg8AAAACAAACaJGc', // Auckland Production Machinery, Channel1, Machine1, Random.Int4
'AsjkYmnsopHs6msy0lKsuLkfdfOwplAs0BbFn7LEQg8AAAACAAACaJGd', // Auckland Production Machinery, Channel1, Machine1, Random.Real4
'AsjkYmnsopHs6msy0lKsuLkfdfOwplAs0BbFn7LEQg8AAAACAAACaJGe', // Auckland Production Machinery, Channel1, Machine1, Random.Real8
'AsjkYmnsopHs6msy0lKsuLkfdfOwplAs0BbFn7LEQg8AAAACAAACaJGf', // Auckland Production Machinery, Channel1, Machine1, Random.String

You can now copy the tag references into the Javascript of your own Web application.

Your application should:

  • Prompt the user for UA Office Link subscription credentials
  • Sign in to the UA Office Link Cloud API with these credentials
  • Start a cloud session
  • Resolve tag references
  • Subscribe to real time data by passing resolved tags

Functional Web Page

The following is a complete albeit simplistic Web page to display live values for the copied tag references:

<!doctype html>
<html lang="en">
<head>
    <meta charset="utf-8" />
    <script src="https://apis.uaofficelink.com/uaolcloud/v1/uaofficelink-cloud-api.min.js"></script>
    <title>UA Office Link Test</title>
    <script>
        var tagRefs = [
            // Paste tag references here; retrieve tag references for your project from https://cloud.uaofficelink.com
            'AsjkYmnsopHs6msy0lKsuLkfdfOwplAs0BbFn7LEQg8AAAACAAACaJGb', // Auckland Production Machinery, Machine1, Random.Int2
            'AsjkYmnsopHs6msy0lKsuLkfdfOwplAs0BbFn7LEQg8AAAACAAACaJGc', // Auckland Production Machinery, Machine1, Random.Int4
            'AsjkYmnsopHs6msy0lKsuLkfdfOwplAs0BbFn7LEQg8AAAACAAACaJGd', // Auckland Production Machinery, Machine1, Random.Real4
            'AsjkYmnsopHs6msy0lKsuLkfdfOwplAs0BbFn7LEQg8AAAACAAACaJGe', // Auckland Production Machinery, Machine1, Random.Real8
            'AsjkYmnsopHs6msy0lKsuLkfdfOwplAs0BbFn7LEQg8AAAACAAACaJGf', // Auckland Production Machinery, Machine1, Random.String
        ];
        var tagIndices = {};    // Dictionary to hold mappings from tagId to tag index
        var elemRefs = [];      // Holds references to the span elements where values are displayed

        // Callback function called after successfully receiving live values
        function onUpdateLiveValues(values){
            var numValues = values.length;
            for (var i=0; i<numValues; i++){
                var value = values[i];
                // map tag ID to index of the display element
                var tagIndex = tagIndices[value.tagId];
                elemRefs[tagIndex].innerText = value.value;
            }
        }

        // Something went wrong ... signing out
        function onUpdateLiveValuesError(error){
            console.log(error);
            UaolCloud.signOut();
            alert('onUpdateLiveValuesError, signed out');
        }

        // Clear values display
        function clearValuesDisplay(){
            for (var i=0; i<5; i++){
                elemRefs[i].innerText = 'undefined';
            }
        }

        // Subscribing to live values using the previously defined tag references
        function subscribeFromTagRefs() {
            var numTags = tagRefs.length;
            // Not passing any access keys, assuming that end-to-end encryption is not used
            var tag = new UaolCloud.Tag();
            UaolCloud.Tag.fromReferenceAsync(tagRefs).then (function (tags) {
                if (tags.length == 0) {
                    console.log('fromReferenceAsync: no tags returned');
                    alert("There don't seem to be any tags available right now.");
                    return;
                }
                var numTags = tags.length;
                if (numTags != tagRefs.length) {
                    console.error('fromReferenceAsync: some tags are not resolved');
                    alert('Only ' + tags.length + ' out of ' + tagRefs.length + ' tags are currently available');
                }
                // Cross reference returned tag ID to index for onUpdateLiveValues callbacks
                for (var i=0; i<numTags; i++) {
                    tagIndices[tags[i].getId()] = i;
                }
                UaolCloud.subscribeAsync(tags).then(function(){
                    // success, onUpdateLiveValues should be called soon
                })
                .catch(function (error) {
                    console.error(error);
                    alert('Tag subscription failed')
                })
            })
            .catch(function (error) {
                console.log(error);
                alert('fromReferenceAsync error');
            });
        }

        // Call the API's signIn method with given credentials
        function onlogin() {
            var userName = document.getElementById('idUserName').value;
            var password = document.getElementById('idPassword').value;
            UaolCloud.signInAsync(userName, password).then(function() {
                alert('Login successful, ready to request live data.');
                clearValuesDisplay();
                // start session, then subscribe to live values
                UaolCloud.startSessionAsync(1000, onUpdateLiveValues, onUpdateLiveValuesError).then(function() {
                    subscribeFromTagRefs();
                })
                .catch(function(error) {
                    console.log(error);
                    alert('startSessionAsync error');
                })
            })
            .catch(function(error){
                alert('Login error')
            });
        }

        // Call the API's signOut method
        function onlogout() {
            UaolCloud.signOut();
            alert('Signed out');
        }

        // Initialise element references of the span elements that will show live values
        function ready() {
            console.log('document loaded');
            for (var i=1; i<=5; i++){
                elemRefs.push(document.getElementById('idTag'+i));
            }
        }

        // call ready method once the document is loaded
        document.addEventListener("DOMContentLoaded", ready);

    </script>
</head>

<body>
    <div>
        <h2>UA Office Link Test</h2>
        <h3>Please sign in</h3>
        <input id='idUserName' type="text" title="username" placeholder="username" />
        <input id='idPassword' type="password" title="username" placeholder="password" />
        <button onclick=onlogin()>Sign In</button>
        <button onclick=onlogout()>Sign Out</button>
    </div>
    <div>
        <h3>Tag values:</h3>
        <table>
            <tr><td>Tag 1 Value:</td><td><span id='idTag1'></span></td></tr>
            <tr><td>Tag 2 Value:</td><td><span id='idTag2'></span></td></tr>
            <tr><td>Tag 3 Value:</td><td><span id='idTag3'></span></td></tr>
            <tr><td>Tag 4 Value:</td><td><span id='idTag4'></span></td></tr>
            <tr><td>Tag 5 Value:</td><td><span id='idTag5'></span></td></tr>
        </table>
    </div>
</body>

</html>

To run the example, copy the above into an html file, replace tag references with your own and open the file in a browser. Then enter your UA Office Link subscription credentials and click on the ‘Sign In’ button. Click OK on the sign-in confirmation dialog when prompted.

../../../_images/testsignin.png

Now live values for the referenced tags begin to flow.

../../../_images/testdata.png

Click on the ‘Sign Out’ button when done.