AVEVA™ Mobile Operator Extensibility API Guide

[Link]
Acknowledgements

AVEVA Mobile Operator Extensibility APIs make use of the following open source software.
Lua
Lua programming language is used to create the Android extensions. Lua is a free software and is distributed
under the MIT License ([Link] [Link] as published
by the Massachusetts Institute of Technology. The source code for Lua is available at
[Link]

© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 2
© 2021 AVEVA Group plc and its subsidiaries. All rights reserved.

No part of this documentation shall be reproduced, stored in a retrieval system, or transmitted by any means,
electronic, mechanical, photocopying, recording, or otherwise, without the prior written permission of AVEVA.
No liability is assumed with respect to the use of the information contained herein.
Although precaution has been taken in the preparation of this documentation, AVEVA assumes no responsibility
for errors or omissions. The information in this documentation is subject to change without notice and does not
represent a commitment on the part of AVEVA. The software described in this documentation is furnished under
a license agreement. This software may be used or copied only in accordance with the terms of such license
agreement.
ArchestrA, Aquis, Avantis, Citect, DYNSIM, eDNA, EYESIM, InBatch, InduSoft, InStep, IntelaTrac, InTouch, OASyS,
PIPEPHASE, PRiSM, PRO/II, PROVISION, ROMeo, SIM4ME, SimCentral, SimSci, Skelta, SmartGlance, Spiral
Software, Termis, WindowMaker, WindowViewer, and Wonderware are trademarks of AVEVA and/or its
subsidiaries. An extensive listing of AVEVA trademarks can be found at: [Link] All other
brands may be trademarks of their respective owners.
Publication date: Monday, January 25, 2021
Contact Information
AVEVA Group plc
High Cross
Madingley Road
Cambridge
CB3 0HB. UK
[Link]
For information on how to contact sales and customer training, see [Link]
For information on how to contact technical support, see [Link]
Contents

Acknowledgements .............................................................................................. 2

Chapter 1 Overview ........................................................................................... 5

Configuring the Extensions ....................................................................................................................5

Chapter 2 Extensibility APIs ............................................................................... 7

IProcNode.............................................................................................................................................7
IExtensionsLog ......................................................................................................................................8
IExtensionsUI ........................................................................................................................................9
Single Control Extensions ............................................................................................................................. 9
Multiple Control Extensions ....................................................................................................................... 12
[Link](ControlPropertyBag) .......................................................................................... 19
IExtensionsSettings ............................................................................................................................. 22
IExtensionsQuery ................................................................................................................................ 23
IDeviceSettings ................................................................................................................................... 25
IExtensionsWebAPI ............................................................................................................................. 25
Get .............................................................................................................................................................. 25
PostFormEncoded ...................................................................................................................................... 26
PostJson ...................................................................................................................................................... 27
Put .............................................................................................................................................................. 28
Delete ......................................................................................................................................................... 29

Appendix A Troubleshooting ........................................................................... 31

Calculation Expression Evaluation Error ............................................................................................... 31

© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 4
Chapter 1

Overview

Note: IntelaTrac is now AVEVA Mobile Operator. However, in some instances, you may see “IntelaTrac” in
upgrade path, reports, and so on.

Configuring the Extensions

Extensibility APIs provide a mechanism to add new functionalities through custom functions to AVEVA Mobile
Operator app. All extensions are synced to AVEVA Mobile Operator app during a Transfer.
To configure extensions
1. Configure all the extensions in the [Link] file.
2. Copy the [Link] and the related lua files to the following folder on the AVEVA Mobile Operator
Server:
<Installation Directory>\AVEVA\Mobile Operator\Server\Extensions\Multiplatform
3. On the AVEVA Mobile Operator app, use Transfer to sync data between the mobile device and the Server.
The extensions are enabled for the AVEVA Mobile Operator.
Note:
- You must code extensions only with lua.
- In case of new or updated extensions, use Transfer to sync the data between the mobile device and the AVEVA
Mobile Operator Server.

[Link] file
The [Link] is a configuration file, which links the GUID (defined in the [Link] file)
with the related lua file.

Properties
 name: Name of the function
 id: Unique ID of the function
 file: Name of the Lua file
 type:Type of function

© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 5
 AVEVA™ Mobile Operator Extensibility API Guide
Chapter 1 – Overview

Example
{
"Config":
[
{
"name": "@DropDownNumber1",
"id":
"1DDFC3DD-A096-4685-8AAA-4448AA31ED8D",
"file": "[Link]",
"type": "custom_function"
},
{
"name": "@DropDownNumber2",
"id":
"1CCFC3AA-A465-4685-8AAA-6868FF31EF8F",
"file": "[Link]",
"type": "custom_function"
}

]
}

© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 6
Chapter 2

Extensibility APIs

IProcNode
This method returns the current node in execution.

Properties
 CurrentNode: Provides access to the properties of the current node.
 ParentNode: Provides access to the properties of the parent node.
 NextSiblingNode: Provides access to the properties of the next sibling node.
 PreviousSiblingNode: Provides access to the properties of the previous sibling node.

Returns
A Lua table of the following IProcNode objects:
Note: IProcNode objects are case-sensitive.

 Alias – string
 Id – string
 ParentId – string
 Required – bool
 DisplayName – string
 IsDynmaicAsset – bool
 Sequence – int
 Value – object
 DataType – data type name as string
 Asset – Table of the following asset properties:
o AllowWorkOrder
o ApplicationId

© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 7
 AVEVA™ Mobile Operator Extensibility API Guide
Chapter 2 – Extensibility APIs

o AssetActualName
o AssetDescription
o AssetTypeId
o ChildCount
o DisplayName
o Epc
o ExtendedProperties
o FromExternal
o Id
o IsDeleted
o ItemOrder
o NameForSorting
o NameToDisplay
o ParentId
o TypeOfAsset

Example

function Calculate(params)

local nextNode = [Link]

local nextNodeAsset = nextNode["Asset"]
local nextNodeAssetName = nextNodeAsset["AssetActualName"]
return nextNodeAssetName

end

IExtensionsLog
This API logs messages to AVEVA Mobile Operator App log file.

Method
 [Link](Message,Level)

Parameters

© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 8
 AVEVA™ Mobile Operator Extensibility API Guide
Chapter 2 – Extensibility APIs

 Message: String displaying the message to log.

 Level: Displays the logging level.

Supported Values:
o ERROR: Displays only error messages.
o WARNING: Displays warnings and error messages.
o INFO: Displays information, warnings, and error messages.
o DEBUG: Displays debug, information, warnings, and error messages.

Example
[Link]("Message to Log.","INFO")

IExtensionsUI
This API displays UI controls.

Types
IExtensionsUI has the following two types:
 Single Control Extension
 Multiple Controls Extension

Single Control Extensions

This method displays a UI control for the custom function.

Method
[Link](TemplateName,TemplateData)

Parameters
 TemplateName: Following are the supported templates.
o MPF_Dropdown: Template name for dropdown list control with string data.
o MPF_Dropdown_Object: Template name for dropdown list control with key value data.
o MPF_MessageBox: Template name for message box control.
 TemplateData: Meta data for the UI object.

© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 9
 AVEVA™ Mobile Operator Extensibility API Guide
Chapter 2 – Extensibility APIs

Dropdown list using String data (MPF_Dropdown)

This template has the following properties:

– Title: Title of the drop down control.
– Dropdown Title: Custom message for the drop down control.
– Data: Contents of the drop down control.

Example:
The below example shows how to populate a Dropdown list Data with cause code string array.

local listData = {}
listData["Title"] = "SAP Response Lists"
listData["DropdownTitle"] = "Cause Codes"
listData["Placeholder"] = "Select Cause Codes"
local listArrayData = { "Cyclic Fatigue","GCB Coid Burnout","GCD Circuit Defective", "GCO
Open Circuit","GCR Corrosion","CER Errosion"}
listData["Data"] = listArrayData
local listReturn = [Link]("MPF_Dropdown",listData)

Dropdown list using Key/Value data (MPF_Dropdown_Object)

This template has the following properties:

– Title: Title of the drop down control.
– Dropdown Title: Custom message for the drop down control.
– Data: Contents of the drop down control.

Example:
The following example shows how to populate a Dropdown list Data with key/value pair strings fetched from
SATM_Response_Lists Table.

local listData ={}

listData["Title"] = "Asset Selection"
listData["DropdownTitle"] = "Asset Display Names"
listData["Placeholder"] = "Select Asset Display Names"
local item ={}
local queryResult = [Link]('select ResponseList_PK , Name from
SATM_Response_Lists' ,{});
local data = queryResult["Rows"]
local col = queryResult["ColumnCount"]
local row = queryResult["RowCount"]

© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 10
 AVEVA™ Mobile Operator Extensibility API Guide
Chapter 2 – Extensibility APIs

for i=1,row,1
do
local key = data[i][1]
local Value = data[i][2]
item[key] = Value
end
listData["Data"] = item
local selectedkey = [Link]("MPF_Dropdown_Object",listData)

Message box (MPF_MessageBox)

This control displays the message with or without an image.

Properties

– Message Title: Title of the message.

– Image: Image file for the message.
– Message: Custom message for the task.

Example 1: Message box with hard-coded message and image

local messageData = {}
messageData["Title"] = "Custom Extension Alert"
messageData["MessageTitle"] = "Message Alert!"
messageData["Image"] = "[Link]"
messageData["Message"]= "<b>IMPORTANT NOTICE:</b><p>If the failures found during visual
inspection can be corrected immediately, then correct failure and record <b>\"As Found\"
as \"Fail\"</b>, with relevant failure code and record <b><u>\"As Left\"</u> as <font
color=green>\"Pass\"</font></b>.</p><p>If failure cannot be corrected immediately, record
<b>\"As Found\" and \"As Left\" as <font color=red>\"Fail\"</font></b> with relevant
<b><i>failure code</i></b>.</li></ul>"
[Link]("MPF_MessageBox",messageData)

Example 2: Message box with message and image queried from a Table

local currentNode = [Link]

local taskID = currentNode["Id"]
local queryResult = [Link]("select [Link], [Link] from
SATM_AttachedDocuments AD inner join SATM_ITEM T on T.Attached_Doc_FK = [Link] and
T.ITEM_PK =@0",{taskID});
local data = queryResult["Rows"]
local messageData = {}
messageData["Title"] = "Custom Message Alert"
messageData["MessageTitle"] = "Warning Alert"
messageData["Image"] = data[1][1]

© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 11
 AVEVA™ Mobile Operator Extensibility API Guide
Chapter 2 – Extensibility APIs

messageData["Message"]= data[1][2]
[Link]("MPF_MessageBox",messageData)

Note:
- Image in the message box is optional. The recommended size for the image is 50 pixels by 50 pixels. Remove
the “Image” property to have the message box without an image.
- Message can be HTML encoded.

Multiple Control Extensions

IExtensionsUI supports rendering of multiple controls in the same view.

Method
 [Link](TemplateName,TemplateData)

Parameters
 TemplateName: MPF_Multi_Control
 TemplateData: Contains metadata of the controls. It has the following properties:
o Title: Title for the custom function
o Control: Collection of UI controls. It contains meta data for each UI control.
Following are the standard properties of a control:
– Title: Title of the control.
– Id: Unique ID of the control. For example, D1.
– ControlType: Type of control. For example, dropdown.
– Visible: Boolean property. Defines the visibility state of the control. By default, the control is visible.
– Disable: Boolean property. Defines the enabled or disabled state of the control. By default, the
control is enabled.

Supported Controls
The following controls are supported as multiple control extensions:
 Dropdown
 Label
 Text Area
 Button

© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 12
 AVEVA™ Mobile Operator Extensibility API Guide
Chapter 2 – Extensibility APIs

 Asset Browser

Apart from the standard properties, each control contain the following specific properties:

Dropdown
This control is used to display drop-down list. Following properties are available for dropdown control:

 Placeholder: Placeholder text of the control.

 Data: Data to list in the control.

Example
local templateData = {}
templateData['Title'] = 'Multi Control Extension Title'

local data = {}
countries[1] ='Country1'
countries[2] ='Country2'
countries[3] ='Country3'

local dropdownData2 = {}
dropdownData2['Id'] ='D2' --
dropdownData2['ControlType'] ='DropDown'
dropdownData2['Visible'] =false
dropdownData2['Title'] ='Dropdown Title'
dropdownData2['PlaceHolder'] ='Select Value'
dropdownData2['Data'] = data

local controls ={}

controls[1] = dropdownData2
templateData['Controls'] = controls
[Link]('MPF_Multi_Control',templateData)

Return Value

This control returns the key of the selected item.

Label
This control is used to display messages. For example, error and warning. Following properties are available for
Label control:
 Text: Display text for the label control.
 Type: Type of message. Following are the supported message types:

© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 13
 AVEVA™ Mobile Operator Extensibility API Guide
Chapter 2 – Extensibility APIs

o Error: Displays error message in red.

o Warning: Displays warning message with warning icon.
o Success: Displays success message with warning icon.
o HTML: Displays HTML encoded text.

Example

local templateData = {}
templateData['Title'] = 'Multi Control Extension Title'

local labelControl = {}
labelControl['Text'] = 'The Selected Node does not contain any Assets'
labelControl['Type'] = 'Error'
labelControl['Visible'] = true
labelControl['ControlType'] = 'Label'
labelControl['Id'] = 'L1'

templateData['Controls'] = controls

[Link]('MPF_Multi_Control',templateData)

Return Value
This control returns an empty string.

Note: Text for the label control can have up to a maximum of 50 characters, for better viewing across all
viewports.

Text Area
This control is used to display user defined text.

 Placeholder: Placeholder text of the control.

 MaxLength: Maximum character length of the control.
 DefaultValue: Default text of the control.

Example

local textAreaControl2 = {}
textAreaControl2['Id'] ='T2'
textAreaControl2['Visible'] = true
textAreaControl2['Title'] = 'Asset Details'
textAreaControl2['Placeholder'] = 'Details'

© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 14
 AVEVA™ Mobile Operator Extensibility API Guide
Chapter 2 – Extensibility APIs

textAreaControl2['MaxLength'] = 100
textAreaControl2['ControlType'] = 'TextArea'
textAreaControl2['DefaultValue'] = ‘Selected Asset'

Note:
- When updating the task, the text area value should be a maximum of 100 characters.
- Set the Visible property to True to make sure the control is displayed in the view.

Button
This control maps a button to the data of a control.

 Text: Display text of the control.

 MappedControlIds: Data can be retrieved from the required controls using the mapped control property. In
the below example Dropdown with ID D1 is mapped to a button, on clicking the value from dropdown is
retrieved.

Example

local buttonControl1 = {}
buttonControl1['Id'] ='B1'
buttonControl1['Text'] = 'Click me to get Asset Details'buttonControl1['MappedControlIds'] =
'D1’
buttonControl1['ControlType'] = 'Button'
buttonControl1['events'] = onclickeventObject

Onclick Event
The onclick event accepts the name of the lua function to call when the button is clicked.
It retrieves and stores the data in a property bag, and updates it to the required control.

Example
The following example shows two drop down lists with IDs D1 and D2, mapped to a button control.
On clicking the button, the values get updated to the text area with the ID T2.

function OnClick(Id,controlData)
local dropdown1value =controlData['D1']
local dropdown2value ='controlData['D2']
local controlPropertyBag ={}
local textAreaPropertyBag ={}
textAreaPropertyBag['SelectedValue']= 'Temprature'
controlPropertyBag['T2'] = textAreaPropertyBag
[Link](controlPropertyBag)

© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 15
 AVEVA™ Mobile Operator Extensibility API Guide
Chapter 2 – Extensibility APIs

end

The lua function specified in the event accepts the following parameters:
 id: ID of the control that raised the event.
 controlData: Lua table containing data of the mapped control ID.

Example:
The following example shows two drop down lists with IDs D1 and D2, mapped to a button control.
On clicking the button, the values from the two dropdown are retrieved, added, and updated to the text area,
using the onclick event.

local onclickeventObject ={}

onclickeventObject['onclick'] = 'OnClick'

Events
Events is a special property available for all controls. It requires the name of the lua function to call.
The following events are supported:
 onchange: Accepts the name of the lua function to call.

Example: onchange
local eventsObject = {}
eventsObject['onchange'] = 'OnCountryChange'
local countryDropdown ={}
countryDropdown[‘onchange’] = eventsObject

The following properties can be updated in an event:

 General Properties
o Visible
o Disable
 Drop-down
o Data
o DefaultValue
 Label
o Text

The lua function specified in the event accepts the following parameters:

© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 16
 AVEVA™ Mobile Operator Extensibility API Guide
Chapter 2 – Extensibility APIs

 id: ID of the control.

 controlData: Lua table containing data of the control which raised the event. controldData has below
properties:
 selectedValue : selected value of the control which raised the event

Note:
- All properties are case sensitive.
- IDs of the controls should be unique.
- Controls will render in the order specified in the lua table.

Asset Browser
This control integrates the asset browser control to the custom function. It helps select an asset from the list of
Assets.

Properties
 NameToDisplay: Displays the name of the asset.
 AssetDescription: Displays the description of the asset.
 AllowWordOrder: Displays whether Work Orders are allowed or not.

Example
assetBrowser1['Id'] = 'A1'
assetBrowser1['Title'] = 'Asset'
assetBrowser1['ControlType'] = 'AssetBrowser'
assetBrowser1['Placeholder'] = 'Select Asset'

Return Value
This control returns the asset information object. The asset information object contains the following list of
properties:
 Asset
 DisplayName
 AssetActualName
 AssetDescription
 AssetTypeId
 Id
 ParentId
 NameToDisplay

© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 17
 AVEVA™ Mobile Operator Extensibility API Guide
Chapter 2 – Extensibility APIs

 AllowWorkOrder
 TypeOfAsset

Note: Use the NameToDisplay property to display the name of the asset.
Example: The below example shows how to access the asset information:
local listReturn = [Link]('MPF_Multi_Control',templateData)
local assetBrowserControl1Value = listReturn['A1']
[Link]('value of AssetDescription ' ..
assetBrowserControl1Value['AssetDescription'],"Debug" )

The Asset property contains the following properties:

 AllowWorkOrder
 ApplicationID
 AssetActualName
 AssetDescription
 AssetTypeId
 ChildCount
 DisplayName
 Epc
 ExtendedProperties
 FromExternal
 Id
 IsDeleted
 ItemOrder
 NameForSorting
 NameToDisplay
 ParentId
 TypeOfAsset

Example
function Initialize()
[Link]("start of Init method","Debug")
[Link] = 0
[Link] = "@StringOutPut"
[Link]("String")
[Link]("End of Init method","Debug")
[Link]("Before calc","Debug")

© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 18
 AVEVA™ Mobile Operator Extensibility API Guide
Chapter 2 – Extensibility APIs

end

function Calculate(params)
[Link]("Start of Calc","Debug")
templateData = {}
templateData['Title'] = 'Multi Control Extension Title'
local controls ={}

local assetBrowser1 = {}
assetBrowser1['Id'] = 'A1'
assetBrowser1['Title'] = ‘ Asset'
assetBrowser1['ControlType'] = 'AssetBrowser'
assetBrowser1['Placeholder'] = 'Select Asset ‘

controls[1] = assetBrowser1

templateData['Controls'] = controls
local listReturn = [Link]('MPF_Multi_Control',templateData)

local assetBrowserControl1Value = listReturn['A1']

local assetDetails = assetBrowserControl1Value['Asset']

[Link]('value of Name to display ' ..

assetBrowserControl1Value['NameToDisplay'],"Debug" ) -- Asset info property
[Link]('value of AssetDescription ' ..
assetBrowserControl1Value['AssetDescription'],"Debug" )-- Asset info property
[Link]('value of AllowWorkOrder ' ..
tostring(assetBrowserControl1Value['AllowWorkOrder']),"Debug" )-- Asset info property

[Link]('value of nested level childcount is ' .. assetDetails['ChildCount'],"Debug"

)-- Asset property
[Link]('value of nested level EPC is ' .. assetDetails['Epc'],"Debug" )-- Asset
property

local assetName = assetBrowserControl1Value['NameToDisplay']

return assetName
end

[Link](ControlPropertyBag)
This API updates the properties of the controls (for example, visible) on control events (for example, onchange).

Parameters
 ControlPropertyBag: Contains the lua table with key and value properties to be updated.
o Key: ID of the control.
o Value: A lua table with the following properties:
– Key: Property name

© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 19
 AVEVA™ Mobile Operator Extensibility API Guide
Chapter 2 – Extensibility APIs

– Value: Property value

Example: Updating Single Control

The below example describes how to consume the parameters, populate other control properties, and call back
the Extension UI, using SetData API, to update the property values accordingly. In this example, it is updating the
States of the selected Country.

function OnCountryChange(id,controlData)
-- access the id of the control
[Link](id,"INFO")
-- access the selected value of the control
local controlValue = controlData['selectedvalue']
--populate the states of the selected country
local states = {}
states1[1] ='state1'
states1[2] ='state2'
states1[3] ='state3'
--create the property bag table to update each property with value along with controlid
local controlPropertyBag ={}
local dropdownControl2PropertyBag = {}
dropdownControl2PropertyBag['Data'] = states
dropdownControl2PropertyBag['Visible'] = true
controlPropertyBag['D2'] = dropdownControl2PropertyBag-- the key should be id of the control
[Link](controlPropertyBag) -- call back Extension UI to update the relevant
properties

end

Example: Updating Multiple Controls

In the following example, we want to update the state dropdown data, along with the text, saying that states
are successfully updated. For this, we need to update multiple control properties.

function OnCountryChange(id,controlData)
-- access the id of the control
[Link](id,"INFO")
-- access the selected value of the control
local controlValue = controlData['selectedvalue']
--populate the states of the selected country
local states = {}
states1[1] ='state1'
states1[2] ='state2'
states1[3] ='state3'
--create the property bag table to update each property with value along with controlid
local controlPropertyBag ={}
local dropdownControl2PropertyBag = {}
dropdownControl2PropertyBag['Data'] = states
dropdownControl2PropertyBag['Visible'] = true
controlPropertyBag['D2'] = dropdownControl2PropertyBag -- the key should be id of the
control

© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 20
 AVEVA™ Mobile Operator Extensibility API Guide
Chapter 2 – Extensibility APIs

local labelControlPropertyBag = {}
labelControlPropertyBag['Text'] = 'States are populated successfully'
labelControlPropertyBag['Visible'] = true;
controlPropertyBag['L1'] = labelControlPropertyBag
[Link](controlPropertyBag) -- call back Extension UI to update the relevant
properties

End

Accessing Control Values

Once the UI Task is completed the template returns the values of selected controls in Lua table. Lua table has
the following properties:
 Key: ID of the control.
 Value: Selected value of the control.

For example, in a multiple control extension with country and state dropdown, following are the return values of
the UI:
 D1 = Country1
 D2 = State1

Example: Return value of Multiple Control Extension

function Calculate(params)

local templateData = {}
templateData['Title'] = 'Multi Control Extension Title'

local countries ={}

countries[1] ='country1'
countries[2] ='country2'
countries[3] ='country3'

local controls ={}

local dropdownData1 = {}
dropdownData1['Title'] ='Country'
dropdownData1['PlaceHolder'] ='Select Country'
dropdownData1['Id'] ='D1'
dropdownData1['Data'] =countries
dropdownData1['ControlType'] ='DropDown'

local dropdownData2 = {}
local states = {}
states[1] ='state1'
states[2] ='state2'
states[3] ='state3'
dropdownData1['Title'] ='State'
dropdownData1['PlaceHolder'] ='Select State'

© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 21
 AVEVA™ Mobile Operator Extensibility API Guide
Chapter 2 – Extensibility APIs

dropdownData1['Id'] ='D2'
dropdownData2['Data'] = states

controls[1] = dropdownData1
controls[2] = dropdownData2

templateData['Controls'] = controls

local controlvalues = [Link]('MPF_Multi_Control',templateData)

local conntrolValueString = ''

if(controlvalues == nil or controlvalues == '')

then
return conntrolValueString
end

for key,value in pairs(controlvalues) --

do conntrolValueString = conntrolValueString .. key .. value
end
[Link](conntrolValueString,"INFO")

return conntrolValueString
end

IExtensionsSettings
This API sets the extensions settings.

Properties
 NumberOfParameters : Sets the number of parameters for the extension.
Type: String
Example:
IExtensionSettings. NumberOfParameters = 1
 DisplayName : Displays the name of the extension.
Type: String
Example:
IExtensionSettings. DisplayName = “GetAsset”

Methods
 SetReturnType(ReturnType): Sets the return type of the extension.
Parameter : String
Supported Types: (“Double”,”Int”,”Float” ,”String”,”Char,””Bool”,”Null”)
Example:
IExtensionSettings. SetReturnType(“Double”)

© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 22
 AVEVA™ Mobile Operator Extensibility API Guide
Chapter 2 – Extensibility APIs

 SetParameterDefinitions(ListofParameterDefinitions): Method to set input Parameter definitions.

Parameter : Array of string
Example:
SetParameterDefinitions({“Definition1”,”Definition2”,”Definition3”})
 SetInputTypes(ListofInputTypes): Method to set Input Types for extensions.
Parameter : Array of string
Example:
IExtensionSettings. SetInputTypes ({“Double”,”String” })

IExtensionsQuery
This API allows querying the SQLite database of the AVEVA Mobile Operator app.
Method
Execute(sql,parameters)

Parameters
 SQL: SQL string to execute.
 Parameters: Array of parameters to be passed for query parameterization.

For example:
[Link]("select Col1 , Col2 from Table where colx1=@0 and colx2
=@1",{val1,val2});

Return
Table with the following properties:
 Status: 0 or 1 , 0 for success 1 for failure
 Error: error message if any
 ColumnCount: number of columns fetched
 ColumnNames: Array of column names
 RowCount: No of rows in result
 Rows: Array of rows fetched

Example 1
[Link]("select AssetName from SATM_Assets where TypeOfAsset=@0 and Allow_WOR
=@1",{0,1});

© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 23
 AVEVA™ Mobile Operator Extensibility API Guide
Chapter 2 – Extensibility APIs

Example 2
[Link]("select AssetName from SATM_Assets LIMIT 100",{});

Example 3
AssetNames contains all the fetched assets from dataset.

local queryResult2 = [Link]('SELECT SATM_ASSETS.AssetPK as Asset,

SATM_ASSETS.AssetName as AssetName FROM SATM_ASSETS WHERE SATM_ASSETS.Owner_FK IN(SELECT
AssetPK FROM SATM_ASSETS WHERE SATM_ASSETS.AssetName = @0)',{assetName})
local data2 = queryResult2["Rows"]
local col2 = queryResult2["ColumnCount"]
local row2 = queryResult2["RowCount"]
[Link]("Query result2 : " ..
queryResult2["Status"],"Debug")
[Link]("Error : " ..
queryResult2["Error"],"Debug")
[Link]("ColumnCount : " ..
queryResult2["ColumnCount"],"Debug")
[Link]("RowCount : " ..
queryResult2["RowCount"],"Debug")

for i=1,row2,1
do
AssetNames[i]= data2[i][2]
end

Notes:
- Allow only Select queries.
- Block the queries on below Security Sync related tables.
- - DBVersion
- - ISMGTM_PERMISSION
- - ISMGTM_USER_DEPARTMENT_LINK
- - SATM_ProcedureRoleLink
- - SATM_Sync_Info
- - SATM_User
- - SATM_Role_user_Base_Link
- - SAT_COR_ORG
- - SAT_COR_SHIFTINFO
- - SAT_SEC_ROLE
- - SATM_Password_History
- - SAT_COR_SHIFTINFO
- - SAT_COR_CREWINFO
- - SAT_COR_CREWROTATION
- - SAT_FAV_USER

© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 24
 AVEVA™ Mobile Operator Extensibility API Guide
Chapter 2 – Extensibility APIs

IDeviceSettings
This API retrieves the device settings with respect to AVEVA Mobile Operator Application.
Properties
It currently supports the following properties:
 CurrentCulture: The locale of the device.
Return type: String (en_US, pt-BR)
For example: local culture = [Link]
Note: For more information on the complete list of language culture names, see Table of Language Culture
Names, Codes, and ISO Values Method [Link]

 ExternalStoragePath: Fully qualified external storage path for AVEVA Mobile Operator Application.
Return Type: String
For example: localstoragepath= [Link]

IExtensionsWebAPI
This API handles the Web API Services from Lua Script.
Types
IExtensionsWebAPI has the following types:
 Get
 PostFormEncoded
 PostJson
 Put
 Delete
Note: A self-signed certificate is not supported. The Web API should have a valid certificate if you are consuming
it on HTTPS.

Get
This method make calls to the Get request of Web API services
Method 1:
[Link](EndPoint, Handler)

Parameters
 EndPoint: Web Api End point of Get request
 Handler: Handler Method of Lua script to handle the response JSON data.

© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 25
 AVEVA™ Mobile Operator Extensibility API Guide
Chapter 2 – Extensibility APIs

Method 2:
[Link](EndPoint, Handler, HeaderCollection)

Parameters
 EndPoint: Web Api End point of Get request
 Handler: Handler Method of Lua script to handle the response JSON data.
 HeaderCollection: Header collection in form of Table

Example
This example will update the text field with first name from the response assuming response is
{
"data": {
"id": 2,
"first_name": "Janet",
"last_name": "Weaver",
"avatar": "[Link]
}
}

Lua Script
local returnvalue = "something"
function Calculate(params)
local headerCollection = {}
headerCollection["ZUMO-API-VERSION"] = "2.0.0"
local response = [Link]("[Link] "Handle",
headerCollection)
return returnvalue
end

function Handle(result)
returnvalue = result["data"]["first_name"]
end

PostFormEncoded
This method calls the POST api which supports the x-www-form-urlencoded post.

Method 1:
[Link](EndPoint, PostData, Handler)

Parameters
 EndPoint: Web Api End point of Get request
 PostData: Data to be posted as Lua table

© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 26
 AVEVA™ Mobile Operator Extensibility API Guide
Chapter 2 – Extensibility APIs

 Handler: Handler Method of Lua script to handle the response JSON data.

Method 2:
[Link](EndPoint, PostData, Handler, HeaderCollection)

Parameters
 EndPoint: Web Api End point of Get request
 PostData: Data to be posted as Lua table
 Handler: Handler Method of Lua script to handle the response JSON data.
 HeaderCollection: Header collection in form of Table

Example

local loginDetail = {}
loginDetail["username"] = "[Link]"
loginDetail["password"] = "Password"

local returnvalue = "something"

function Calculate(params)
local headerCollection = {}
headerCollection["ZUMO-API-VERSION"] = "2.0.0"
local response =
[Link]("[Link] loginDetail,
"Handle", headerCollection)
return returnvalue
end

function Handle(result)
returnvalue = result["data"]["first_name"]
end

PostJson
This method calls the POST api which expects post data in JSON format.

Method 1:
[Link](EndPoint, PostData, Handler)

Parameters
 EndPoint: Web Api End point of Get request

© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 27
 AVEVA™ Mobile Operator Extensibility API Guide
Chapter 2 – Extensibility APIs

 PostData: Data to be posted as string in JSON fromat

 Handler: Handler Method of Lua script to handle the response JSON data.

Method 2:
[Link](EndPoint, PostData, Handler, HeaderCollection)

Parameters
 EndPoint: Web Api End point of Get request
 PostData: Data to be posted as string in JSON fromat
 Handler: Handler Method of Lua script to handle the response JSON data.
 HeaderCollection: Header collection in form of Table

Example

local postdata = '{"name": "paul rudd", "movies": ["I Love You Man", "Role Models"]}'

local returnvalue = "something"

function Calculate(params)
local headerCollection = {}
headerCollection["ZUMO-API-VERSION"] = "2.0.0"
local response = [Link]("[Link]
postdata, "Handle", headerCollection)
return returnvalue
end

function Handle(result)
returnvalue = result["data"]["name"]
end

Put
This method will be used for calling PUT api. The data should be in JSON fromat.

Method 1:
[Link](EndPoint, Data, Handler)

Parameters
 EndPoint: Web Api End point of Get request
 Data: Data to be be updated as string in JSON fromat

© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 28
 AVEVA™ Mobile Operator Extensibility API Guide
Chapter 2 – Extensibility APIs

 Handler: Handler Method of Lua script to handle the response JSON data.

Method 2:
[Link](EndPoint, Data, Handler, HeaderCollection)

Parameters
 EndPoint: Web Api End point of Get request
 Data: Data to be updated as string in JSON fromat
 Handler: Handler Method of Lua script to handle the response JSON data.
 HeaderCollection: Header collection in form of Table
Example
local data = '{"name": "paul rudd"}'

local returnvalue = "something"

function Calculate(params)
local headerCollection = {}
headerCollection["ZUMO-API-VERSION"] = "2.0.0"
local response = [Link]("[Link] data,
"Handle", headerCollection)
return returnvalue
end

function Handle(result)
returnvalue = result["data"]["name"]
end

Delete
This method is used to call Delete Api endpoint.

Method 1:
[Link](EndPoint, Handler)

Parameters
 EndPoint: Web Api End point of Get request
 Handler: Handler Method of Lua script to handle the response JSON data.

Method 2:
[Link](EndPoint, Handler, HeaderCollection)

© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 29
 AVEVA™ Mobile Operator Extensibility API Guide
Chapter 2 – Extensibility APIs

Parameters
 EndPoint: Web Api End point of Get request
 Handler: Handler Method of Lua script to handle the response JSON data.
 HeaderCollection: Header collection in form of Table

Example
local returnvalue = "something"
function Calculate(params)
local headerCollection = {}
headerCollection["ZUMO-API-VERSION"] = "2.0.0"
local response = [Link]("[Link] "Handle",
headerCollection)
return returnvalue
end

function Handle(result)
returnvalue = result["data"]["name"]
end

© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 30
Appendix A

Troubleshooting

This appendix lists some of the errors or problems you may encounter while using AVEVA Mobile Operator
Extensibility APIs.

Calculation Expression Evaluation Error

If the custom function ID (guid) specified in the class for the assembly does not match with the ID of the custom
function specified in the [Link] file, the user is presented with the following error message:

Calculation expression evaluation error.. Stack Trace: [Link]: Calculation expression

evaluation error. ---> [Link]:
Invalid operator/function in the calculation expression: @CSGetCatalogCodes
at [Link]
([Link] s) <0x6cb9da90 + 0x002ac> in <filename unknown>:0
at [Link]
([Link]`1 arrTokens, [Link]`1 arrPrefix,
IDataContext dataContext, Boolean OldCalcExpression) <0x6cb9a028 + 0x00413> in <filename
unknown>:0
at [Link]
([Link] calcExpression) <0x6cb99210 + 0x000e7> in <filename unknown>:0
at [Link]
([Link] currentProcedure, Boolean
updateReferenceNodes) <0x6cb54b10 + 0x00177> in <filename unknown>:0
--- End of inner exception stack trace ---

To resolve this issue, make sure the custom function ID (guid) and the ID of the custom function specified in the
[Link] file are the same.

© 2021 AVEVA Group plc and its subsidiaries. All rights reserved. Page 31