Third Party Application Integration

Owned by Shaun Forbes
Last updated: 01 Nov, 2011Version comment

WeaveLink

WeaveLink is a Windows COM API that can be used for communication between Weave and another application or web page. See this page for more information about installing and testing WeaveLink.

The WeaveLink COM API provides the following functionality:

  • Locate an existing browser instance running Weave
  • Create a new browser running Weave if an existing one can't be found
  • Bring the Weave browser to the front of other windows
  • Execute an action in the Weave client and return the results
  • Listen for events fired by the Weave client

As you can see the actual functionality provided by the API is very limited, with most of the actual work being performed by the Weave client running in the browser. This simplified API means that new functions can be called without the need to upgrade the WeaveLink components on every client PC.

Unfortunately this also means that a certain amount of boiler plate code needs to be added to actually make us of this API, work is underway to provide a higher level API in Weave 2.4 that sits on top of the WeaveLink API and provides functionality in terms of entities, maps, etc, but this page documents the WeaveLink COM API.

Getting a link to the Weave client

Unless indicated otherwise all code samples below were written and tested using Visual Basic in Visual Studio 2005.

But it's possible to use the WeaveLink COM API in older and newer version of Visual Basic and Visual Studio, as well as Windows Scripting Host and even VBScript or JavaScript within a web page.

The first step when communicating with the Weave client is to create a WeaveLink.ILink object.

The basic interface for this class is contained in WeaveLink.dll with either WeaveLinkImpl.exe or WeaveLinkDebug.exe providing the implementation.

If you have a Weave instance available then WeaveLinkImpl.exe should be used, if you don't then WeaveLinkDebug.exe can be used to provide a test harness.

This class provides a way to:

  • Obtain a reference to a Weave client
  • Check what version of the WeaveLink API is being used (useful for weakly types languages)
  • Obtain a reference to a Sink that can used to respond to events triggered in the Weave client

So to create the ILink object you would use something like the following

Dim link As WeaveLink.ILink
link = CreateObject("Weave.Link")

Then once you have a link you can obtain a reference to a Weave client by using its Client method.

Dim client As WeaveLink.IClient
client = link.Client("Weave HTML Client", "http://wrath:8080/weave/main.html")

This will locate a running instance of Internet Explorer that contains the Weave client based on the window title given as the first parameter, or start a new instance using the second parameter if it can't find one.

Communicating with the Weave client

Once we have a reference to the client we can then call actions that are provided by the JavaScript embedded in the client by using the Send() method of the IClient class.

The Send() method takes an action id and a parameter string, in JSON format, and passes that to the Weave client and returns the results of that action in a Result object.

The Result class provides an Error Boolean property that indicates if there was an error executing the action, if the Error property is true then the operation failed and the Value property of the Result will be a String describing the problem. If the Error property is false then the Value property will return an object that is the actual response from the action.

Dim response As WeaveLink.Result

response = client.Send("com.cohga.GetActiveEntity", "{}")
If response.Error Then
    MsgBox(response.Value, MsgBoxStyle.Exclamation, "Error")
Else
    Dim entity As String
    entity = response.Value
End If

response = client.Send("com.cohga.SetActiveEntity", "{entity: 'property'}")
If response.Error Then
    MsgBox(response.Value, MsgBoxStyle.Exclamation, "Error")
End If

From here it's just a matter of knowing what actions are available, what parameters they require and what they return.

Actions available in Weave 2.3

com.cohga.ZoomSelection

Parameters

name

type

optional

description

entity

string

yes

The id of the entity who's selection should be zoomed to, the active entity will be used if this parameter isn't supplied

Zoom to the selection of the property entity

response = client.Send("com.cohga.ZoomSelection", "{entity: 'property'}")
If response.Error Then
    MsgBox(response.Value, MsgBoxStyle.Exclamation, "Error")
End If

Zoom to the current selection of the active entity

response = client.Send("com.cohga.ZoomSelection", "{}")
If response.Error Then
    MsgBox(response.Value, MsgBoxStyle.Exclamation, "Error")
End If

com.cohga.SetSelection

Parameters

name

type

optional

description

entity

string

no

The id of the entity who's selection should be updated

ids

object or object[]

no

The id or array of ids to update the selection with

operator

'REPLACE', 'ADD', 'REMOVE', 'REFINE', 'CLEAR'

yes

Determines what will be done with the selection set relative to the current selection, the default if not set is 'REPLACE'

clearOthers

boolean

yes

If true the selections for all other entities will be cleared during the processing of this action, if false or not set then other entities selections will be untouched

active

boolean

yes

If true or not set then the active entity will also be changed to this entity, if set to false then the active entity won't be changed

zoom

boolean

yes

If true or not set then the map will also zoom to the new selection extent, if set to false then the map extent won't be changed 

response = client.Send("com.cohga.SetSelection", "{entity: 'property', ids: [11000, 11001], clearOthers: true}")
If response.Error Then
    MsgBox(response.Value, MsgBoxStyle.Exclamation, "Error")
End If

response = client.Send("com.cohga.SetSelection", "{entity: 'roads', ids: ['PENNY LANE', 'BOURBON STREET', 'ELECTRIC AVENUE'], active: false, zoom: false, operator: 'ADD'}")
If response.Error Then
    MsgBox(response.Value, MsgBoxStyle.Exclamation, "Error")
End If

com.cohga.GetSelection

Parameters

name

type

optional

description

entity

String or String[]

yes

The id, or array of id's, of the entity who's selection should be retrieved, if not set then all entities that the user has access to will be returned

returnids

Boolean

yes

If true or not set then the current list of id will also be returned, if set to false then only the current size of the selection will be returned

Return

name

type

optional

description

entity

String

no

The id of the entity who's selection is being returned

size

Integer

no

The number of unique identifiers currently selected for the entity

ids

Object[]

yes

The individual id's for the entity, not included if returnids is set to false

Regardless of how many entities are requested this action will always return an array of object of the above format.

response = client.Send("com.cohga.GetSelection", "{entity: 'property', returnids: false}")
If Not response.Error And Not response.Value Is Nothing Then
    Dim count As Integer
    Dim i As Integer
    count = CallByName(response.Value, "length", CallType.Get)
    For i = 0 To count - 1
        Dim v As Object
        v = CallByName(response.Value, i, CallType.Get)
        Debug.Print(v.entity & " " & v.size)
    Next
End If

property 2

response = client.Send("com.cohga.GetSelection", "{entity: ['property', 'roads'], returnids: false}")
    If Not response.Error And Not response.Value Is Nothing Then
    Dim count As Integer
    Dim i As Integer
    count = CallByName(response.Value, "length", CallType.Get)
    For i = 0 To count - 1
        Dim v As Object
        v = CallByName(response.Value, i, CallType.Get)
        Debug.Print(v.entity & " " & v.size)
    Next
End If

property 2
roads 6

response = client.Send("com.cohga.GetSelection", "{returnids: false}")
If Not response.Error And Not response.Value Is Nothing Then
    Dim count As Integer
    Dim i As Integer
    count = CallByName(response.Value, "length", CallType.Get)
    For i = 0 To count - 1
        Dim v As Object
        v = CallByName(response.Value, i, CallType.Get)
        Debug.Print(v.entity & " " & v.size)
    Next
End If

buildings 0
property 2
busstops 0
roads 6
drainage 0
development_applications 0
hydrants 0
suburbs 0

response = client.Send("com.cohga.GetSelection", "{entity: 'roads'}")
If Not response.Error And Not response.Value Is Nothing Then
    Dim count As Integer
    Dim i As Integer
    count = CallByName(response.Value, "length", CallType.Get)
    For i = 0 To count - 1
        Dim v As Object
        v = CallByName(response.Value, i, CallType.Get)
        Debug.Print(v.entity & " " & v.size)
        Dim ids As Object
        Dim idcount As Integer
        Dim j As Integer
        ids = CallByName(v, "ids", CallType.Get)
        idcount = CallByName(ids, "length", CallType.Get)
        For j = 0 To idcount - 1
            Debug.Print(CallByName(ids, j, CallType.Get))
        Next
    Next
End If

roads 6
ABBEY ROAD
BOURBON STREET
LONELY AVENUE
PENNY LANE
ELECTRIC AVENUE
GASOLINE ALLEY

com.cohga.SetActiveEntity

com.cohga.GetActiveEntity

com.cohga.BeginUpdate

com.cohga.EndUpdate

Actions available in Weave 2.4

com.cohga.ZoomSelection

com.cohga.SetSelection

com.cohga.GetSelection

com.cohga.SetActiveEntity

com.cohga.BeginUpdate

com.cohga.EndUpdate

com.cohga.ClearSelection

com.cohga.GetActiveEntity

com.cohga.GetEntities

com.cohga.GetEntity

com.cohga.GetExtent

com.cohga.SetExtent

com.cohga.SetLocation

com.cohga.GetLocation

com.cohga.GetScales

com.cohga.GetVersion

Parameters

name

type

optional

description

item

string or string[]

yes

The id or, array of id's, of the item who's version should be return, if null then version number for all components will be returned

Return

name

type

optional

description

item

String

no

The name of the item

version

String

no

The version string, format will always be major[.minor[.release]], where major, minor and release will be numeric and minor and release are optional

major

Integer

no

The major version number of the item

minor

Integer

yes

The minor version number of the item

release

Integer

yes

The release version number of the components

If one item is requested then only 1 object of this format will be returned, if multiple items (even if only 1 item requested finds a match) or all items are requested then an array of objects of this format will be returned.

response = client.Send("com.cohga.GetVersion", "{item: 'weave'}")
If Not response.Error Then
    Dim v As Object
    v = response.Value
    Debug.Print(v.Item & " " & v.Version & " " & v.Major & " " & v.Minor & " " & v.Release)
End If

weave 2.4 2 4

response = client.Send("com.cohga.GetVersion", "{item: ['client', 'weave']}")
If Not response.Error And Not response.Value Is Nothing Then
    Dim count As Integer
    Dim i As Integer
    count = CallByName(response.Value, "length", CallType.Get)
    For i = 0 To count - 1
        Dim v As Object
        v = CallByName(response.Value, i, CallType.Get)
        Debug.Print(v.Item & " " & v.Version & " " & v.Major & " " & v.Minor & " " & v.Release)
    Next
End If

client 2.1.1 2 1 1
weave 2.4 2 4

response = client.Send("com.cohga.GetVersion")
If Not response.Error And Not response.Value Is Nothing Then
    Dim count As Integer
    Dim i As Integer
    count = CallByName(response.Value, "length", CallType.Get)
    For i = 0 To count - 1
        Dim v As Object
        v = CallByName(response.Value, i, CallType.Get)
        Debug.Print(v.Item & " " & v.Version & " " & v.Major & " " & v.Minor & " " & v.Release)
    Next
End If

weave 2.4 2 4
client 2.1.1 2 1 1
interop 2.1.0 2 1 0