All SDK functionality is wrapped in a "kSDKv1" namespace. This stands for Kiptr SDK version 1.

As versions update, we will be increasing the version number but you still will be able to use older versions if you like.

General functions


METHODSClick on Methods for further information
Category
getread
Special
ElementgetElementInfo()readElement()

Chain


readChain()

FilegetFile()

saveTextToFile()
Object


objectsByXPath()


Element


getElementInfo(id)

ParametersReturns
Function returns full element information in a form of javascript object. Parameter ”id” can be either an element full tag, a system id of the tag (comes in element object) or a system variable “elementId” which contains a system ID of the element script is executed from.

id – (string or number) System ID, full tag of the element to read or system variable “elementId”.

JS object with full element information – ({ }). JS object contains an array “children” with information about all the children of the element; JS object “element” with info about the element itself, JS object “parent” with info about elements’ parent element and JS object “project” with info about the root project element (this element contains info about full name and full tag separators, project owner and other system info)


Note:

  1. This is an asynchronous function. It has to be used with the “await” operator (or .then method) or it will return the promise. Since “await” can only be used inside an asynchronous function, it is recommended to “wrap” your code in a self-executing asynchronous function (see example below).


Example: 

var execute = (async function myFunction () {
let elemDataFull = await kSDKv1.getElementInfo(elementId);
console.log(elemDataFull);// -> full info about the element containing this script
console.log(elemDataFull.parent.id);// -> system ID of the parent element
console.log(elemDataFull.children.length);// -> number of children of the element
containing this script
console.log(elemDataFull.children[0].tag);// -> short tag of first child
console.log(elemDataFull.parent.fullTag);// -> ful tag of the parent
var tagSeparator = elemDataFull.project.elementFields.find(u => u.name === 'Full tag separator').value;
console.log(tagSeparator);// -> full tag separator character for this project
})();



readElement(id)

ParametersReturns
Function returns element information in a form of javascript object. Parameter ”id” can be either an element full tag, a system id of the tag (comes in element object) or a system variable “elementId” which contains a system ID of the element script is executed from.

id – (string or number) System ID, full tag of the element to read or system variable “elementId”.

JS object – ({ })


Note:

  1. This is an asynchronous function. It has to be used with the “await” operator (or .then method) or it will return the promise. Since “await” can only be used inside an asynchronous function, it is recommended to “wrap” your code in a self-executing asynchronous function (see example below).
  2. All non-system fields (created by users) are included in an array “elementFields”. You can use a help function (see example) to search both system and user fields using one command.


Example: 

var execute = (async function myFunction () {
let elemInfo = await kSDKv1.readElement(elementId);
console.log(elemInfo); // -> info about the element containing this script
console.log(elemInfo.id); // -> system ID of this element
console.log(elemInfo.fullTag); // -> full tag of this element
console.log(elemInfo.parentId); // -> system ID of this elements' parent
console.log(fieldValByName(elemInfo, "User defined field")); // -> value of the field with name "User defined field"
function fieldValByName(element, fieldName) { // Help function
          if (typeof element !== "object") throw new Error(`Element type is not object. Instead got ${typeof element}`);
          if (typeof fieldName !== "string") throw new Error(`fieldName type is not string. Instead got ${typeof fieldName}`);
          if (!element.fieldName) {
               for (let i = 0; i < element.elementFields.length; i++) {
                    if (element.elementFields[i].name == fieldName) {
                        let result;
                        element.elementFields[i].value ? (result = element.elementFields[i].value) : (result= 0);
                        return result;
                    }
               }
          } else if (!!element.fieldName) return element.fieldName;
         else return null;
}
})();


Chain



readChain(id)

ParametersReturns
Function returns element information and all of its children information. Parameter ”id” can be either an element full tag, a system id of the tag (comes in element object) or a system variable “elementId” which contains a system ID of the element script is executed from.

id – (string or number) System ID, full tag of the element to read or system variable “elementId”.

Array of JS objects– ([{ }])


Note:

  1. This is an asynchronous function. It has to be used with the “await” operator (or .then method) or it will return the promise. Since “await” can only be used inside an asynchronous function, it is recommended to “wrap” your code in a self-executing asynchronous function (see example below).


Example: 

var execute = (async function myFunction () {
let elemChain = await kSDKv1.readChain(elementId);
console.log(elemChain); // -> array of elements
console.log(elemChain.length - 1); // -> number of children of current element
})();


File



getFile(id)

ParametersReturns
Function returns a blob of the attached file. Only an element with type “Document” can have an attached file. Parameter ”id” can be either an element full tag, a system id of the tag (comes in element object).

id – (string or number) System ID or full tag of the element with type “Document”

File contents – (Blob)


Note:

  1. This is an asynchronous function. It has to be used with the “await” operator (or .then method) or it will return the promise. Since “await” can only be used inside an asynchronous function, it is recommended to “wrap” your code in a self-executing asynchronous function (see example below).
  2. l5x files are text files.
  3. Kiptr has SheetJS (community edition) already built-in. SheetJS is a popular parser and writer for various spreadsheet formats.More information about it can be found here: https://docs.sheetjs.com/


Example: 

var execute = (async function myFunction () {
let textFileBlob = await kSDKv1.getFile("PRJ003-DOC001"); // Reading text file blob
console.log(await textFileBlob.text()); // Converting blob to text
let xlsxFileBlob = await kSDKv1.getFile("PRJ003-DOC002"); // Reading .xlsx file blob
let arrayBuf = await xlsxFileBlob.arrayBuffer(); // Converting to ArrayBuffer
let newArray = new Uint8Array(arrayBuf); // Creating uint8 array
var workbook = XLSX.read(newArray, { type: "array" }); // Creating a SheetJS workbook
// Workbook object:
console.log(workbook);
// Field A1 value
console.log(workbook.Sheets.Sheet1.A1.v);
})();



saveTextToFile(textToWrite, fileName)

ParametersReturns
Saves text from textToWrite to a plain text file with the name fileName.

textToWrite – (string) Text to be saved.

fileName – (string) Name of the file. Has to include extension.

Nodes that match the xpath expression – ([Element])


Example 

var myText = "Some text";
saveTextToFile(myText, "myNewFile.txt");


Object



objectsByXPath(xmidata, xpath)

ParametersReturns
Function returns an array of all nodes that match the "xpath" expression, in the same order as they appear in the "xmldata". This is a simplified implementation of Document Object Model (DOM) Document.evaluate() method with resultType = "ORDERED_NODE_SNAPSHOT_TYPE".

xmldata – (XMLDocument) Document to search in.


xpath – (string) A string representing the XPath to be evaluated.

Nodes that match the xpath expression – ([Element])


Example 1: 

var newXML = `
         <MyXMLNode Name = "MyNode" Version = "1.0">
         <SubNode Name = "Subnode 1" Parameter1 = "Somevalue"/>
         </MyXMLNode>
`;
let parser = new DOMParser();
let xmlDoc = parser.parseFromString(newXML,"text/xml");
let subnode = kSDKv1.objectsByXPath(xmlDoc, "/MyXMLNode/SubNode")[0];
console.log(subnode.getAttribute("Name")); // -> "Subnode 1"

Example 2: 

var newPrj = new kSDKv1.l5xProject();
newPrj.setName("NewProject");
var controller = kSDKv1.objectsByXPath (newPrj.l5xdata,
"/RSLogix5000Content/Controller")[0];
console.log(controller.getAttribute("Name")); // -> "NewProject"

You will find more info about l5xProject class and setName() method in the Knowledge base.


In the example above we retrieve the name of the project using objectsByXPath function. Kiptr library allows an easier way to do the same:

var newPrj = new kSDKv1.l5xProject();
newPrj.setName("NewProject");
console.log(newPrj.getName()); //-> "NewProject"

You may need to use objectsByXPath function to cover anything that is not natively covered by Kiptr L5X library.