Aras Innovator 11. Programmer s Guide

Transcription

1 Dcument #: Last Mdified: 12/18/2015

2 Cpyright Infrmatin Cpyright 2015 Aras Crpratin. All Rights Reserved. Aras Crpratin 300 Brickstne Square Suite 700 Andver, MA Phne: Fax: Website: Ntice f Rights Cpyright 2015 by Aras Crpratin. This material may be distributed nly subject t the terms and cnditins set frth in the Open Publicatin License, V1.0 r later (the latest versin is presently available at Distributin f substantively mdified versins f this dcument is prhibited withut the explicit permissin f the cpyright hlder. Distributin f the wrk r derivative f the wrk in any standard (paper) bk frm fr cmmercial purpses is prhibited unless prir permissin is btained frm the cpyright hlder. Aras Innvatr, Aras, and the Aras Crp "A" lg are registered trademarks f Aras Crpratin in the United States and ther cuntries. All ther trademarks referenced herein are the prperty f their respective wners. Ntice f Liability The infrmatin cntained in this dcument is distributed n an "As Is" basis, withut warranty f any kind, express r implied, including, but nt limited t, the implied warranties f merchantability and fitness fr a particular purpse r a warranty f nninfringement. Aras shall have n liability t any persn r entity with respect t any lss r damage caused r alleged t be caused directly r indirectly by the infrmatin cntained in this dcument r by the sftware r hardware prducts described herein Aras Crpratin All Cpyrights Reserved. 2

3 Table f Cntents Send Us Yur Cmments... 6 Dcument Cnventins Intrductin The Item The Aras Markup Language (AML) Methds and the IOM AML <Item> Tag <Relatinships> Tag <prperty> Tags Attributes Item Attributes Prperty Attributes IOM Reference IOMCredentials Class Innvatr Class Item Class Base Methds Blean Methds Attribute Methds Prperty Methds Relatinship Methds Item Cllectin Methds Lgical Methds Creating New Item Methd Errr Methds Extended Item Class methds Methds Item Actins Extend the Item Class Cntext Item Methds are Item Factries Handling the Wrng ItemType Methdlgy Built in Actin Methds Generic Methds Cntext Item Methds are Item Factries Methdlgy Aras Crpratin All Cpyrights Reserved. 3

4 4.4 Server Events Cntext Item Methdlgy Available Server Events Client Events Cntext Item Frm Events Field Events Grid Events Item Type Events Item Actins and Server Event Actin Items Client Side Methd Rules Server Side Methd Rules Use Cases Client side - has cache Item is dirty Client side - n cache Item - n item_query value Client side - has cache Item nt dirty - n item_query value Client side - has cache Item nt dirty - has item_query value Client side - n cache Item - has item_query value Server side - has cache Item is dirty Server side - n cache Item - n item_query value Server side - has cache Item nt dirty - n item_query value Server side - has cache Item nt dirty - has item_query value Server side - n cache Item - has item_query value Aras Innvatr Methdlgy Ckbk Create an Aras Innvatr Object Create an Item Object Query fr an Item Query and iterate ver a set f Items Query fr an Item and return its cnfiguratin Query using AML t cnstruct the query Query fr the Item next prmtin states Query using relatinships as search criteria Add an Item cnfiguratin in ne transactin Add a Named Permissin Set a Private Permissin fr an Item Apply a Generic Methd Need t Save text t a File Need t Send frm a Methd Need t Add an UI Cntrl Need fr Speed ApplySQL Need a callback fr a Relatinships Grid Rw Event Need a callback fr a Relatinships Grid Cell Event Shw relatinships in a Grid cntrl n the Frm Open the relatinships in an Excel Dcument Aras Crpratin All Cpyrights Reserved. 4

5 7.21 Want the Identities fr the User Want a field t be either a sequence r user entered value Want t Vault a File Want t get an existing Vaulted File and save it with a new Dcument Want t pen a Vaulted File in Wrd Need t reject an Item Prmte Hw t build XML fr grid Hw t build XML fr a Menu Hw t handle multilingual prperties Hw t handle date prperties Hw t pass values frm nbefrex t nafterx events Hw t reference custm DLL frm server methd Hw t add sub menus t cntext menu in search grid Aras Innvatr Slutin Studi Features Debugging Enabling Debugging in Aras Innvatr Setting up VS.NET 2012 t debug Server side Methds Setting up VS.NET 2012 t debug Client side Methds Setting up the server side lgging External APIs NET IOM COM-cmpatible IOM RT IOM ios IOM Andrid IOM SOAP Requests Aras Crpratin All Cpyrights Reserved. 5

6 Send Us Yur Cmments Aras Crpratin welcmes yur cmments and suggestins n the quality and usefulness f this dcument. Yur input is an imprtant part f the infrmatin used fr future revisins. Did yu find any errrs? Is the infrmatin clearly presented? D yu need mre infrmatin? If s, where and what level f detail? Are the examples crrect? D yu need mre examples? What features did yu like mst? If yu find any errrs r have any ther suggestins fr imprvement, indicate the dcument title, and the chapter, sectin, and page number (if available). Yu can send cmments t us in the fllwing ways: Supprt@aras.cm Subject: Aras Innvatr Dcumentatin Or, Or, Pstal service: Aras Crpratin 300 Brickstne Square Suite 700 Andver, MA Attentin: Aras Innvatr Dcumentatin FAX: Attn: Aras Innvatr Dcumentatin If yu wuld like a reply, prvide yur name, address, address, and telephne number. If yu have usage issues with the sftware, visit Aras Crpratin All Cpyrights Reserved. 6

7 Dcument Cnventins The fllwing table highlights the dcument cnventins used in the dcument: Dcument Cnventins Cnventin Bld Cde Yellw highlight Yellw highlight with red text Nte: Italics Descriptin This shws the names f menu items, dialg bxes, dialg bx elements, and cmmands. Example: Click OK. Cde examples appear in curier text. It may represent text yu type r data yu read. Cde with yellw highlight is used t draw attentin t the cde that is being indicated in the cntent. Red clr text with yellw highlight is used t indicate the cde parameter that needs t be changed r replaced. Reference t ther dcuments. Ntes cntain additinal useful infrmatin. Warning Successive menu chices Warning cntains imprtant infrmatin. Pay special attentin t infrmatin highlighted this way. Successive menu chices may appear with a greater than sign (-->) between the items that yu will select cnsecutively. Example: Navigate t File --> Save --> OK Aras Crpratin All Cpyrights Reserved. 7

8 1 Intrductin The purpse f this dcument is t prvide a Guide t Prgramming Aras Innvatr. It cvers key aspects f prgramming Aras Innvatr fr implementing yur wn business lgic within the Aras Innvatr Enterprise Applicatin Framewrk. This dcument is indented t be used as a Desktp Reference and User Guide cvering the fllwing tpics: The AML (Aras Markup Language), which is the language that drives the Aras Innvatr server. The IOM (Innvatr Object Mdel), which is the Object API fr the AML. Explains hw Methds wrk and the Methdlgy fr implement yur wn business lgic. A Ckbk f recipes fr perfrming cmmn tasks. The.NET cntrls API the Innvatr Client is built n. 1.1 The Item Everything in Aras Innvatr is an Item, which is an instance f an ItemType, which itself is an Item; illustrating that Aras Innvatr is a self-describing system. Dn't get hung up n the self-describing nature n Aras Innvatr and fcus n the simplicity that everything eventually is an Item. Items may have relatinships t ther Items illustrating that Items has structure. Relatinships are defined by RelatinshipType, which is an Item that has three prperties t define the RelatinshipType rule fr the surce (parent) Item, related (child) Item, and relatinship Item, which defines. When the RelatinshipType is created an is_relatinship ItemType is als created named the same as the RelatinshipType and its id is the value t the relatinship_id Prperty n the RelatinshipType. This can get a bit cnfusing but simply put there is a RelatinshipType/ItemType pairing t define the RelatinshipType rule and an ItemType t stre the relatinship Items. Relatinship Items have a related_id Prperty f type Item, which is the related (child) Item fr the relatinship. The related_id Prperty is a link that pints t an Item. The relatinship Item als has a surce_id Prperty f type Item and is the surce (parent) Item fr the relatinship. S, in Aras Innvatr everything is an Item, and Items may have relatinships, which are Items that has surce and related Item Prperties frming an Item cnfiguratin. Fr example, an ItemType Item has Prperty relatinships and this Item cnfiguratin maps directly t the relatinal database fr persistent strage f the Item instances. Every ItemType has a matching relatinal TABLE where the Prperty names are the COLUMN names. 1.2 The Aras Markup Language (AML) The Aras Markup Language (AML) is an XML dialect that fllws the simple /Item/Relatinships/Item/Relatinships repeating pattern t describe Item cnfiguratins. Clients submit AML dcuments t the Aras Innvatr server and receive an AML dcument back. An AML dcument cntains data (Items), structure (Relatinships, which are hierarchical Items), and lgic (an actin t perfrm sme business lgic n the Item). Each Item in the AML dcument has an actin attribute, which is the name f an Aras Innvatr Methd that perfrms business lgic n the Item. The Aras Innvatr server interprets AML dcuments similar t scripting languages, AML dcuments are ften referred t as AML scripts Aras Crpratin All Cpyrights Reserved. 8

9 This is an example f a BOM in AML language: <Item type="part" actin="add"> <item_number> </item_number> <descriptin>sme Assy</descriptin> <Relatinships> <Item type="part BOM" actin="add"> <quantity>10</quantity> <related_id> <Item type="part" actin="add"> <item_number> </item_number> <descriptin>1/4w 10% 10K Resistr</descriptin> </Item> </related_id> </Item> </Relatinships> </Item> 1.3 Methds and the IOM The IOM (Innvatr Object Mdel r Item Object Mdel) is an Object Mdel n tp f the AML. It prvides the ability t build and submit AML dcuments t the Aras Innvatr Server using a simple Object API. There is the Methd ItemType, which are used t implement user defined business lgic. Methds are written in JavaScript, C#, r VB.Net and use the IOM API t implement the business lgic. The fllwing is a Methd in JavaScript using the IOM that is the same as the AML BOM example abve: var innvatr = new Innvatr(); var partitem = innvatr.newitem("part","add"); partitem.setprperty("item_number", " "); partitem.setprperty("descriptin", "Sme Assy"); var bmitem = innvatr.newitem("part BOM","add"); bmitem.setprperty("quantity", "10"); var relateditem = new Item("Part","add"); relateditem.setprperty("item_number", " "); relateditem.setprperty("descriptin", "1/4w 10% 10K Resistr"); bmitem.setrelateditem(relateditem); partitem.addrelatinship(bmitem) ; var resultitem = partitem.apply(); 2015 Aras Crpratin All Cpyrights Reserved. 9

10 2 AML The AML is the XML dialect and language that drives the Aras Innvatr server. Clients submit AML dcuments t the Aras Innvatr server via HTTP. The server parses the AML applying the business lgic defined as the actin attribute fr the Items in the AML dcument, and an AML dcument is returned. The AML dialect is very simple and the fllwing tags define the AML language: 2.1 <Item> Tag The <Item> tag defines an Item instance. XML is case sensitive (ntice the capitalized Item.) There are three principle attributes fr the Item tag t define the Item instance: id the unique ID fr the Item. type the ItemType name fr the Item. actin the name f the Methd that is applied t the Item. There are ther attributes but these are the mst significant, which defines the Item and the actin t apply n it. The fllwing is an AML query example requesting a Part Item by ID: <Item type="part" id="acbdef " actin="get"/> Refer t sectin 4.2 Built in Actin Methds fr the list f Innvatr pre-built actins. 2.2 <Relatinships> Tag Items can have relatinships t ther Items. The <Relatinships> tag is a cntainer tag that hlds the set f relatinship Items. Again ntice the capitalized Relatinships. There are n attributes fr the tag it is a cntainer. With relatinships it is pssible t describe an Item cnfiguratin t any level deep as necessary. The fllwing is an AML query example requesting a Part Item and its BOM relatinships: <Item type="part" id="acbdef " actin="get"> <Relatinships> <Item type="bom" actin="get"/> </Relatinships> </Item> 2.3 <prperty> Tags Prperties fr the Item are the nested tags directly belw the <Item> tag. The Prperty name is the tag name. Fr example, a Part ItemType may have the prperties: item_number, descriptin, and cst, which are als the tag names in the AML. Prperty names are lwercase s the prperty tag names are als lwercase Aras Crpratin All Cpyrights Reserved. 10

11 The fllwing AML illustrates a simple Item cnfiguratin fr describing a Part t Part BOM relatinship: <Item type="part" actin="add"> <item_number> </item_number> <descriptin>sme Assy</descriptin> <Relatinships> <Item type="part BOM" actin="add"> <quantity>10</quantity> <related_id> <Item type="part" actin="add"> <item_number> </item_number> <descriptin>1/4w 10% 10K Resistr</descriptin> </Item> </related_id> </Item> </Relatinships> </Item> Prperty values always use lcale-neutral frmats. Decimal and flat values use the perid symbl (.) as the decimal separatr and n digit separatr (i.e. cmmas separating thusands). The dash symbl (-) is used t dente a negative value. Date/Time values shuld be in YYYY-MM-DD[Thh:mm:ss] frmat and in the lcal (r crprate) time zne. Language-specific values use the xml:lang attribute t specify the language cde. Fr example: <Item type="part"> <item_number> </item_number> <i18n:name xml:lang="de" xmlns:i18n=" <i18n:name xml:lang="en" xmlns:i18n=" <cst>232.13</cst> <created_n> t08:12:02</created_n> </Item> 2.4 Attributes Prperties are used t define the data fr an Item; attributes are meta-data fr the Item r Prperty, which are used t cntrl the server lgic and Methds. Think f attributes like cmmand line switches, r as arguments t a functin. In additin t the type, id, and actin attributes mentined abve there are several additinal attributes used t cntrl the server. The fllwing is the attribute reference fr the <Item> tag: Item Attributes Attribute Type Usage type String The ItemType name fr which the Item is an instance. id String The unique ID value fr the Item instance Aras Crpratin All Cpyrights Reserved. 11

12 Attribute Type Usage where String Used instead f the id attribute t specify the WHERE clause fr the search criteria. Include the table name with the clumn name using the dt ntatin: where= user.first_name like 'Tm%' actin String The name f the Methd (r Built in Actin Methd) t apply t the Item. dgetitem Blean If 0 then d nt perfrm a final get actin n the Item after the server perfrmed that actin as defined by the actin attribute. Default is 1. Used with actin="get" select String A cmma delimited list f prperty names (clumn names) t return which is the SELECT clause in the SQL statement. rderby String A cmma delimited list f prperty names (clumn names) t rder the results and is the ORDER BY clause in the SQL statement. page Integer The page number fr the results set. pagesize Integer The page size fr the results set. maxrecrds Integer This defines the abslute maximum Items t be searched in the database. levels Integer The Item cnfiguratin depth t be returned. This shuld be used with cautin because f the perfrmance hit due t its lack f granularity in the data fetched. Use the nested Relatinships style f defining yur queries t d the same thing but with far greater perfrmance. serverevents Blean If 0 then disable the server events imprving perfrmance. Default is 1. iscriteria Blean If 0 then include the nested structure fr the Item cnfiguratin in the respnse but dn't use it as search criteria. Default is 1, which uses the nested structure in the request as search criteria. related_expa nd Blean If 0 then d nt expand the related_id Prperty fr the relatinship Items t include the related Item. Anther wrd returns its ID. language String A cmma-delimited list f language cdes, r "*" t return all languages. Multilingual prperty values is returned (if present) fr all specified languages. Used with actin="update" edit versin Blean If 0 then dn't versin an Item n update. Default is 1, which is versin the Item (if it s a versinable Item) n update Aras Crpratin All Cpyrights Reserved. 12

13 Attribute Type Usage serverevents Blean If 0 then disable the server events imprving perfrmance. Default is 1. Only Update events are disabled, Lck events can be executed if using Edit Prperty Attributes Attribute type keyed_name cnditin Usage The ItemType name fr which the item is an instance f. This is the keyed_name Prperty fr the Item referenced by the Item type Prperty. This is the cnditin value fr the AML query. The cnditin value is any valid SELECT cnditin supprted by the database. This is the list f pssible cnditin values: Cnditin eq ne ge le gt Cmments The SQL cnditinal symbls: =, <>, <=, >=, >, and < are expressed as tw letter mnemnic wrd: eq, ne, le, ge, gt, and lt Example: <name cnditin="gt">100</name> lt like nt like between nt between in nt in The value fr the Prperty tag wuld include wild card symbls, which are % fr any characters and _ fr a single character. Example:<name cnditin="like">tm%</name> This is a range cnditin and yu wuld include the AND keywrd in the Prperty tag value. Example: <cst cnditin="between">10.00 and 50.00</cst> This is a set based cnditin where the value fr the Prperty tag is a cmma delimited list f values fr the set. Example: 2015 Aras Crpratin All Cpyrights Reserved. 13

14 Attribute Usage is is null is nt null <name cnditin="in">'tm', 'Peter', 'Je'</name> Pssible values fr the Prperty tag culd be null r nt null. Example: <cst cnditin="is null"/> <cst cnditin="is nt null"/> Xml:lang Language cde fr multilingual prperties. Must be used in cnjunctin with the internatinalizatin namespace n the prperty tag. Fr example: <i18n:name xml:lang="de" xmlns:i18n=" Aras Crpratin All Cpyrights Reserved. 14

15 3 IOM Reference IOM Reference prvides a general descriptin f the IOM (Innvatr Object Mdel r Item Object Mdel) API. A mre detailed API reference may be btained frm ne f the fllwing: On-line: G t Under the sectin Other Dcuments, click On-Line API Guide.html. Frm Innvatr Client UI: Lgin as Innvatr Administratr. Under the Help menu, select API Reference. In Innvatr CD Image: G t the dcumentatin flder and pen Aras Innvatr - API Guide.html. The IOM is an Object Mdel fr the AML, but it is nt purely Object Oriented. Using Object Oriented terms, an ItemType is like a Class and the Item is like an Object. Althugh the Item is an Object with methds, there is nly ne Item Class fr all ItemTypes. In a pure Object Oriented representatin, there wuld be a Class fr each ItemType because each ItemType has its wn set f Prperties t describe the different Items. An Item Object is intended t be abstract and pliable; depending f its internal structure, the Item Object usually represents ne f five fllwing supprted types f IOM Items: Single Innvatr Item f an arbitrary ItemType. Set f Innvatr Items, as in the case fr results f the actin get when mre than ne Item returns. Errr, as in the case when an actin request results in errr frm the Innvatr Server. Result t represent an arbitrary text wrapped by <Result> XML tags. Lgical t represent a set f prperties wrapped in lgical statement by ne f lgical XML tags: <r>, <and>, r <nt>; usually used t specify the search criteria fr the actin get. The IOM is intended t be a generic and cmpact API fr mdeling the Item structure f the AML as abstract Objects. The majrity f the methds fr the IOM deals with memry management f the AML dcument fr the Item Object. The AML is a script sent as a message t the Aras Innvatr Server; the IOM is an Object API t build the AML messages, submit them t the Innvatr Server and parse an AML dcument that is returned by the Server. There are tw majr types f methds in the Item Class: methds that nly wrk with item's AML in memry and methds that cmmunicate with the Server, i.e. send request(s) t and get respnse(s) frm the server. All get\set type f methds as well as isxxx(...) (e.g. iserrr(), iscllectin(), etc.) and add\remve methds (e.g. addrelatinship(...), remveprperty(...), etc.) belng t the frmer grup. Methds like fetchxxx(...) (e.g. fetchlckstatus()), apply(...), (...), prmte(...), lck\unlckitem(...), etc. belng t the latter grup. In case methd sends a request t the server it must be explicitly mentined in the API reference methd cmments Aras Crpratin All Cpyrights Reserved. 15

16 Nte: The term methd has tw meanings in this guide; the typgraphical cnventin used thrughut this Guide is as fllws: Lwercase methd refers t methds n an IOM Item Object. Capitalized Methd refers t Methd Items stred in the Aras Innvatr database. Sample cde is shwn in Curier 10pt fnt. Optinal arguments are surrunded by [] characters. 3.1 IOMCredentials Class The IOMCredentials Class defines the lgin credentials fr cnnecting t the Aras Innvatr Server. The Item Class has a credentials public prperty, which is an IOMCredentials Object. Typically, yu d nt need t knw abut r deal with the credentials Object because the Methds run in lgged in sessin. Yu can, hwever, set the credentials fr the Item Object using these methds, if yu want t submit the apply requests t a different Aras Innvatr server. The IOMCredentials Class methds are mstly getters and setters fr URLs (Innvatr and Vault servers), DB name, and lgin name and passwrd. 3.2 Innvatr Class In Innvatr Class, methds like applyaml( ), applymethd( ), and applysql( ), being type Item, send the apply request t the Aras Innvatr Server. In respnse, the Server creates XML that apply_ methds used t cnstruct an Item Object t return; methds like getitembyid( ) and getitembykeyedname( ) search the database the lgged in sessin is cnnected t, and methds like newitem( ), newerrr( ) and newresult( ) cnstruct a new instance f the Item Object. Other members f this class perfrm miscellaneus nn-item related peratins. Use them if yu need t get a new GUID (methds getnewid() ), generate a next sequence value (methd getnextsequence( ) ), r calculate the MD5 hash value fr a given string (methd ScalcMD5( ).) 3.3 Item Class An Item Object can represent an Item, r a set f Items, r an Errr. Item public cnstructr has ne required argument itemtype-name and ne ptinal argument actin. The new Item is nly ppulated with the Prperties and default values frm the ItemType when the ptinal actin argument is add. The Item Class public field dm represents a DOM Object that hlds the data fr the Item in the AML frmat Base Methds The Item Class base methd apply( )submit the AML apply request t Innvatr Server using the cntext Item DOM as AML surce and returns a new Item built n the XML returned by the Server. In cntrast, the base methd ladaml( ) des nt return a new Item but rather rebuilds this.dm using AML taken as an argument Aras Crpratin All Cpyrights Reserved. 16

17 Yu can call clne( )methd t get a new identical instance f the cntext Item and yu can call setnewid() methd t replace the cntext Item id by newly generated GUID Blean Methds Call methd iscllectin()t find ut whether r nt the Item represents a set f Items, e. g. whether r nt its dm prperty hlds mre than ne Item nde. Call iserrr()methd t find ut whether r nt the Item represents an Errr. See IOM API n-line reference fr mre blean members f the Item Class Attribute Methds Methds such as getactin(), getid(), and gettype() return a value f Item nde actin, id, and type attribute respectively, while methd getattribute( ) takes an attribute-name as an argument and, therefre, can be used t get any attribute by name. Thus, getactin()is a shrt cut t getattribute( actin ), getid() is a shrt cut t getattribute( id ), and s n. Each get methd in this grup has a crrespnding set methd: setactin( ), setid( ),settype( ), and setattribute( ). Ntice that methd setattribute( ) nt nly sets new value fr an existing attribute but can als add a new attribute t the Item nde and then sets its value Prperty Methds Prperty methds cmprise set f accessrs t Item prperties and Item prperty s attributes: get_, set_ (which acts als as add_), and remve_. In additin, if prperty has/need a nested Item there are methds t get/insert such nested Item. Accessrs t Prperties are getprperty( ), setprperty( ), and remveprperty( ).These methds take then prperty name as an argument. Accessrs t Prperty s attribute are getprpertyattribute( ), setprpertyattribute( ), and remveprpertyattribute( ). These methds take prperty and attribute names as arguments. Methd setprperty( )/setprpertyattribute( )nt nly sets new value fr an existing Item prperty/ prperty s attributes but creates new prperty/ prperty s attributes and then sets its value if the prperty/ prperty s attributes with a given name des nt yet exist. The setprperty methd requires prperty values t be in a lcale-neutral frmat. Decimal and flat values shuld use the perid symbl (.) as the decimal separatr and n digit separatr (i.e. cmmas separating thusands). The dash symbl (-) shuld be used t dente a negative value. Date/Time values shuld be in YYYY-MM-DD[Thh:mm:ss] frmat and in the lcal (r crprate) time zne. Language-specific values shuld be set using the language cde as the third argument. Accessrs t Prperty s nested Item are: getprpertyitem( ), setprpertyitem( ), and createprpertyitem( ). All these methds take prperty name as an argument, and methd setprpertyitem( ) needs, in additin, an Item Object as the secnd argument t create a DOM fr the nested Item Aras Crpratin All Cpyrights Reserved. 17

18 3.3.5 Relatinship Methds Relatinship methds cmprise set f Item s relatinship accessrs: getrelatinships( ), addrelatinship( ), createrelatinship( ), and remverelatinship( ). The difference between createrelatinship( ) and addrelatinship( ), tw methds that bth are adding an Item nde t the Relatinship parent nde, is subtle. Let s cnsider the fllwing server-side VB methd t illustrate hw createrelatinship( ) wrks: Dim myinnvatr As Innvatr = Me.getInnvatr() Dim myitem As Item = myinnvatr.newitem("mytype","myactin") myitem.createrelatinship("user","add") This cde results in fllwing myitem.dm XML <Item isnew="1" istemp="1" type="mytype" actin="myactin"> <Relatinships> <Item isnew="1" istemp="1" type="user" actin="add" /> </Relatinships> </Item> Similar cde that exercises addrelatinship( ) methds is Dim myinnvatr As Innvatr = Me.getInnvatr() Dim myitem As Item = myinnvatr.newitem("mytype","myactin") Dim relitem As Item = myinnvatr.newitem("user","add") myitem.addrelatinship(relitem) and this cde results in fllwing myitem.dm XML: <Item isnew="1" istemp="1" type="mytype" actin="myactin"> <Relatinships> <Item isnew="1" istemp="1" type="user" actin="add" id="7ea3f18935cc493a900dab63e839fda2"> <classificatin>/*</classificatin> <default_vault>67bbb9204fe84a8981ed ba06c</default_vault> </Item> </Relatinships> </Item> As yu can see addrelatinship( ) prduces in this case mre detailed Item nde under the Relatinship parent nde. There are three methds getrelateditem( ), setrelateditem( ), and createrelateditem( ) that are valid fr relatinship Item nly and are used as a shrt cut t the Item.get/setPrpertyItem() methds Item Cllectin Methds This grup cmprises methds t wrk with cllectins. Cllectin in this cntext is a set f Items as in the case fr results frm a query. Methd appenditem( ) appends its Item Object argument t an existing cllectin r cnverts a single Item instance t set f Items. This mechanism is illustrated in a C# sample belw: Innvatr myinnvatr = this.getinnvatr(); Item myitem = myinnvatr.newitem("mytype","myactin"); 2015 Aras Crpratin All Cpyrights Reserved. 18

19 At this pint, myitem presents a single Item instance, myitem.dm XML lks like this: <Item isnew="1" istemp="1" type="mytype" actin="myactin" /> and myitem.iscllectin() returns false. But three extra line f cde: Item addeditem = myinnvatr.newitem("added","myactin"); // set ID t be able t remve addeditem later addeditem.setid(myinnvatr.getnewid()); myitem.appenditem(addeditem); cnverts myitem t a cllectin, e.g. myitem.iscllectin() returns true, and myitem.dm XML becmes as fllwing: <AML> <Item isnew="1" istemp="1" type="mytype" actin="myactin" /> <Item isnew="1" istemp="1" type="added" actin="myactin" id="b12f9384b1de4c4f8158c36d18269be9" /> </AML> If the Item bject id is nt NULL it can be remved frm the cllectin: myitem.remveitem(addeditem); Use getitemcunt() methd t determine the size f a cllectin, getitembyindex( ) methd t get an instance f the Item Object based n its psitin inside f the cllectin, and methd getitemsbyxpath( ) t find an Item by its XPath Lgical Methds The methds newor(), newand(), and newnot() insert lgical nde with tag <r>, <and> and <nt> respectively under the parent Item nde and return an Item Object that represent a newly inserted lgical nde. Fr example, the cde belw : Innvatr myinnvatr = this.getinnvatr(); Item myitem = myinnvatr.newitem("mytype","myactin"); Item lgicalor = myitem.newor(); lgicalor.setprperty("f", "bar"); prduces the fllwing myitem.dm XML: <Item isnew="1" istemp="1" type="mytype" actin="myactin"> <r> <f>bar</f> </r> </Item> The methd remvelgical( ) remves a lgical nde specified by methd s argument Creating New Item Methd User can create a new item using methd newitem( ). See cde samples in sectins fr the methd usage illustratin Errr Methds Errr methds cmprise set f accessrs t Errr specific prperties such as faultcde (methds get/seterrrcde( ),) faultstring (methds get/seterrrstring( ),) faultactr (get/seterrrsurce( ),) and detail (methds get/seterrrdetail( ).) 2015 Aras Crpratin All Cpyrights Reserved. 19

20 Thus, the cde sample belw: Innvatr myinnvatr = this.getinnvatr(); Item errr = myinnvatr.newerrr("default detail"); errr.seterrrcde("any number"); errr.seterrrstring("hell, Wrld"); errr.seterrrsurce("mymethd"); errr.seterrrdetail("new detail"); prduces the fllwing Errr Item DOM: <Envelpe xmlns:xsd=" <Bdy> <Fault> <faultcde>any number</faultcde> <faultstring>hell, Wrld</faultstring> <faultactr>mymethd</faultactr> <detail>new detail</detail> </Fault> </Bdy> </Envelpe> Extended Item Class methds This set f methds implements specific functinality n the Item, which extends the base Item Class. Fr purpse f reference all the Extended Item Class methds are rganized in fur categries Getting Innvatr reference methd: getinnvatr() see examples f usage in sectins 3.2. Lck methds: lckitem() unlckitem() Life Cycle methd: prmte( ) Wrkflw methds: instantiatewrkflw( ) The fllwing methds are bslete and will be remved frm future releases: startwrkflw( ) use Item.apply( startwrkflw ) instead. cancelwrkflw( ) - use Item.apply( cancelwrkflw ) instead. clsewrkflw( ) - use Item.apply( clsewrkflw ) instead. The detailed characteristic and usage illustratin f methds abve is left utside the scpe f the dcument. See n-line API reference fr mre details Aras Crpratin All Cpyrights Reserved. 20

21 4 Methds Business lgic in Aras Innvatr is implemented using Methd Items and are written in JavaScript, C#, r VB.Net ften using the IOM t interact with Aras Innvatr Items. There are three ways t implement Methds in Aras Innvatr n the server side: Item Actin Methds which extend the Item Class and perfrm lgic n Item instances. Generic Methds, which implement arbitrary lgic. Server Events which implement lgic n the cntext Item befre and\r after the server perates n the Item. Similarly there are three ways t implement Methds in Aras Innvatr n the client side: Item Methds which extend the Item Class and perfrm lgic n Item instances. Generic Methds, which implement arbitrary lgic. Frm, Field, and Grid Events which implement lgic n client side UI events. Client Events that can be attached t an Item Type; triggered when user s interactin with Innvatr UI generate a new Item. The Methd Item has a cmment Prperty that yu can use t anntate the Methd and can be seen when yu search and review the Methds as mentined abve. 4.1 Item Actins Extend the Item Class One purpse fr Methds is t extend the Item Class. Methds extend the Item Class when they are bund as the related Item fr Item Actin relatinships n the ItemType. In the AML the Methd name is the actin attribute name fr the Item tag. <Item type="my ItemType" actin="my Methd" id=" "/> The Methd culd be called using the IOM like this (all three examples belw are equivalent and are written in C#): 1) Item myitem = this.newitem("my ItemType", "My Methd"); myitem.setid(this.getid()); Item results = myitem.apply(); 2) Item myitem = this.newitem("my ItemType"); myitem.setid(this.getid()); Item results = myitem.apply("my Methd"); 3) Item myitem = this.newitem(); myitem.setid(this.getid()); myitem.settype("my ItemType"); myitem.setactin("my Methd"); Item results = myitem.apply(); 2015 Aras Crpratin All Cpyrights Reserved. 21

22 4.1.1 Cntext Item As it was mentined abve Item Actin Methds are executed n an instance f Item which is called cntext item (read sectin 5 Actin Items fr mre details n hw cntext item is btained fr Item Actin Methds). The cntext item must be referenced inside Item Actin Methds as the this keywrd in JavaScript, and C#, and the Me keywrd Object in VB.Net. The cntext item is an instance f IOM Item class; crrespndingly any methds f IOM Item class (see sectin 3.3 fr mre details) culd be called n the cntext item, e.g this.getprperty( f ) (C#) r Me.getPrperty( f ) (VB.Net). Nte: In rder t be able t execute Methd s cde Innvatr plugs it int a particular template that prvides required cde attributes (methd and class bundaries, imprt statements, etc.). Each supprted language (JavaScript, C#, VB.NET, etc.) have several available templates in Innvatr. All written in the sectin is applied t default templates (there is ne default template per supprted language). Methds can explicitly redefine the template that is used during the methd cmpilatin. Usage f alternative templates and methdlgy f writing valid Methds fr them is left utside the scpe f the dcument Methds are Item Factries Methds fllw the Factry design pattern in that they return an Item r Errr Object. The Item Actin Methd must return an Item, which ften is the result f an Item.apply() methd call; typically the last step in the business lgic fr the Methd. There are several ways t create an Item; the fllwing IOM methds return an Item Object: Item.apply(), Item.newItem(), Item.clne(), Innvatr.newItem(), Innvatr.newResult(), and Innvatr.newErrr(). C# Item qryitem = this.newitem(this.gettype(), "get"); qryitem.setid(this.getid()); qryitem.setlevels(1); return qryitem.apply(); If the Methd needs t return an Errr then use the Innvatr.newErrr(text) methd. C# Innvatr innvatr = this.getinnvatr(); return innvatr.newerrr("this methd has <b>failed</b>."); Handling the Wrng ItemType Smetimes it is desirable t share the same Methd fr many ItemTypes. Hwever, there are cases in which the Methd is intended t be used nly by an Item f a specific ItemType. The way yu can prevent the use f a Methd with a cntext item f a wrng type is t thrw an exceptin when the wrng ItemType is used (this is what the cre Item Class methds d when the ItemType is nt f the specific desired value). Here is a sample f what shuld be dne in a Methd that needs t perate n a specific type f Item: 2015 Aras Crpratin All Cpyrights Reserved. 22

23 C# Innvatr innvatr = this.getinnvatr(); if (this.gettype()!= "My ItemType") { return innvatr.newerrr("item must be f type 'My ItemType'"); return null; Methdlgy One f the principle cncepts in prgramming Aras Innvatr is t write Methds called n Items. The Item Actin relatinships n ItemTypes simulate Object Oriented prgramming, where the ItemType is the Class and Item Actin relatinships t Methds are the Class methds. Literally the Methd cde is cmpiled dynamically t extend the Item Class with this methd and calls it (see als ntes t 0). Similar t class instance in OO prgramming the cntext item is an bject n which Methds are perfrmed. At the same time there are sme peculiarities in hw t use cntext item in Innvatr s Item Actin Methds. One imprtant details abut Item Actin Methds is that they must always return an Item which is cnsidered as the result f wrk dne by the Item Actin Methd. An Item Actin Methd might wrk with cntext item but the cntext item is used here mre as an input value (it s still must be referenced as this r Me frm inside Methds). It s highly recmmended that Item Actin Methds d nt change the cntext item but rather create a new item that is returned frm the methd. Yu can use the cmbinatin f the Item.getPrperty( ) methd with the Item.setPrperty( ) methd t ppulate the new temprary Item r use the Item.clne( ) methd t cnstruct the new Item frm the cntext item. If develper f Methd s cde has chsen t mdify the cntext item and nt create a new item, the cntext item must be returned frm the methd. 4.2 Built in Actin Methds The Methd name is passed as the actin attribute fr the <Item> tag in AML. <Item type="my ItemType" actin="my Methd" id=" "/> But in additin t Methd names as the actin attribute value there is als a set f Built in Actin Methds. These are basically the same as Methds but yu cannt find them in the database when searching the Methd Items. Nevertheless, they are called the same way as rdinary Methds via the actin attribute. This is a reference fr Built in Actin Methds. Built in Actin Methd add update Cmments Add the Item as an instance f an ItemType. Updates the Item. The Item must be lcked Aras Crpratin All Cpyrights Reserved. 23

24 Built in Actin Methd purge delete get getitemcnfig Cmments If the Item is versinable and is being updated the first time since being lcked the update versins the Item applying the update t the new versin, unless the versin= 0 attribute is specified, which disables the versining. Delete the versin f the Item. Delete all versins f the Item. The purge and delete are the same fr nnversinable Items. Gets the Item(s) and its cnfiguratin based n the AML Item cnfiguratin used t query the database. This returns the Item cnfiguratin as described by the standard AML query. The AML in and ut are n different than the standard actin= get. The GetItemCnfig is ptimized by limiting the lgic dne between the SQL call and the AML result. The perfrmance imprvement is gained by limiting the features typically available in Innvatr GetItem (n server events r access checking n the sub level Items). edit create merge lck unlck versin This lcks, updates, and unlcks the Item. This acts as a get if the Item exists, therwise acts as an add. This acts as an edit if the Item exists, therwise acts as an add. This lcks the Item and is the same as the Item.lckItem() methd. This lcks the Item and is the same as the Item.unlckItem() methd. This creates a new generatin f an Item, clearing the lcked_by_id f the riginating Item and setting the lcked_by_id in the new generatin. It then applies an update t the newly created generatin. The server events triggered in the fllwing sequence: nbefreversin, nafterversin, nbefreupdate, nafterupdate. If the item is nt versinable, an exceptin is thrwn. 4.3 Generic Methds Generic Methds are used t perfrm arbitrary business lgic. They can be used t perfrm any lgic yu require and its input Item is up t yu. They are called in the IOM with the Innvatr.applyMethd( ) methd Aras Crpratin All Cpyrights Reserved. 24

25 4.3.1 Cntext Item The cntext Item is the this keywrd Object in JavaScript and C#, and is the Me Object in VB.Net. The XML data fr the cntext Item is the XML submitted as the paylad fr the request and it may nt be valid AML, just well frmatted XML. It des nt matter it is the input fr the Generic Methd and can be whatever yu want it t be Methds are Item Factries The Generic Methd must return an Item r an Errr similar t Item Actin Methds. Often the result f the Generic Methd is sme simply text r an HTML fragment. The text can be returned using the Innvatr.newResult(text) methd and if the Methd needs t return an Errr then use Innvatr.newErrr(text) methd. C# Innvatr innvatr = this.getinnvatr(); return innvatr.newresult("this methd was <b>successful</b>."); OR Innvatr innvatr = this.getinnvatr(); return innvatr.newerrr("this methd has <b>failed</b>."); C# Example Innvatr innvatr = this.getinnvatr(); Item item = this.newitem("user", "get"); Item results = item.apply(); int cunt = results.getitemcunt(); if (cunt<1) return innvatr.newerrr("n users fund."); StringBuilder cntent = new StringBuilder(); cntent.append("<table>"); fr (int i=0; i<cunt; ++i) { Item user = results.getitembyindex(i); cntent.append("<tr><td>lgin Name:</td><td>"); cntent.append(user.getprperty("lgin_name")); cntent.append("</td></tr>"); cntent.append("</table>"); return innvatr.newresult(cntent.tstring()); Methdlgy Typically all yu need are simply name/value pairs as input fr yur Methd and thse are like Prperty tags fr the Item. The bdy fr the Generic Methd is nested inside an <Item> tag s yu can pass name/value pair as arguments t the Generic Methds like rdinary Prperty tags. The Item passed as the cntext Item can represent any Item yu want including fictitius Items, plus yu have the added advantage f cntinuing using the IOM API t perate n the cntext Item Object Aras Crpratin All Cpyrights Reserved. 25

26 4.4 Server Events Purpse f Server Event Methds is t either perfrm sme custm actins either befre (OnBefreXXX) r after (OnAfterXXX) a particular server actin (like add, delete, etc.) r fully replace the actin prcessing n server (OnXXX). Detailed infrmatin abut available in Innvatr server events culd be fund in sectin Cntext Item In case f Server Event Methd the cntext item is a direct analgy f a class instance (i.e. bject) in OO prgramming in a sense that the Methd perates n its cntext item (as it was mentined abve the cntext item culd be referenced as the this keywrd in JavaScript and C#, and the Me keywrd Object in VB.Net frm inside the Methd). In ther wrds the purpse f a Server Event culd be defined as changing the cntext item, s mdified cntext item is the result f wrk dne by Server Event Methd. Of curse, Server Event Methd desn t necessarily have t alter its cntext item but rather perfrm sme ther actins (e.g. lg sme inf; send ; etc.); this is usually typical fr Methds perfrmed n OnAfterXXX event Methdlgy A Server Event Methd might return an Item nly if it wants t return an errr. Otherwise Server Event Methd may nt have a return statement. C# Innvatr innvatr = this.getinnvatr(); return innvatr.newerrr("this methd failed."); In the case Methd is called as the OnBefreXXX event and it returns an errr, the cntext Item is replaced with an Errr Item and is simply passed n thrugh t the client and n further server actin is taken. In the case f an OnAfterXXX event the server rlls back the transactin and passes the Errr back n thrugh t the client. It s imprtant t understand that Server Event Methds that are called n OnBefreXXX events perate n request AML sent frm client; Server Event Methds that are called n OnAfterXXX events perate n respnse AML that server is abut t send back t client and Server Event Methds that fully replace server actins (OnXXX) get client request AML as cntext item and must replace it with respnse AML that is passed n thrugh t the client. In ther wrds, it s imprtant t remember that Server Event Methds called n OnBefreXXX events are invked befre server parses the request and after the Methd is dne the cntext item must have a valid request AML frmat (it culd be mdified by the methd but it still shuld have a valid frmat s that server wuld be able t parse it). Frm ther side, Server Event Methds called n OnAfterXXX events are invked after server prcessed the request, and after the Methd is dne the cntext item must have a valid respnse AML frmat (it culd be mdified, e.g. Methd culd ppulate it with federated data, but it shuld be valid respnse AML, s that client wuld be able t parse it.) Available Server Events The fllwing Server Events are currently available in Innvatr. Each event belw is fllwed by a shrt descriptin and an example f cmmn use. OnBefreAdd 2015 Aras Crpratin All Cpyrights Reserved. 26

27 OnAfterAdd OnAdd Runs befre an item is added t the database (thrugh the add, create r merge actins.) OnBefreAdd methds are ften used fr validatin purpses (e.g. t make sure the prperty values d nt vilate a business rule). The same methd that is called OnBefreAdd is ften als called OnBefreUpdate, t perfrm the same validatin. Runs after an item is added t the database (thrugh the add, create r merge actins), but befre it is returned t the client. OnAfterAdd methds can be used t synchrnize with ther items r with external systems (e.g. add a new part number t ERP). Runs in place f the built-in add actin (via add, create r merge). Neither OnBefreAdd nr OnAfterAdd events are called when using OnAdd. An OnAdd methd cmpletely replaces the built-in add actin, and wuld typically be used fr federated items. The methd is expected t create the apprpriate recrds in the database and frm a prper AML respnse. Failure t d either is likely t result in an errr. OnBefreUpdate Runs befre an item is updated in the database (thrugh the update, edit r merge actins.) OnBefreUpdate methds are ften used fr validatin purpses (ften alng with OnBefreAdd). The request may either be rejected cmpletely (by returning an errr) r mdified t cnfrm t the prper rules. OnAfterUpdate OnUpdate Runs after an item is updated in the database (thrugh the update, edit r merge actins), but befre it is returned t the client. OnAfterUpdate methds can be used t synchrnize with ther items r with external systems (e.g. updating a part descriptin in ERP). Runs in place f the built-in update actin (via update, edit r merge). Neither OnBefreUpdate nr OnAfterUpdate events are called when using OnUpdate. An OnUpdate methd cmpletely replaces the built-in update actin, and wuld typically be used fr federated items. The methd is expected t mdify the apprpriate recrds in the database and frm a prper AML respnse. OnBefreDelete Runs befre an item is deleted (thrugh the delete r purge actins.) OnBefreDelete methds are typically used t cancel a delete peratin based n a business rule. OnAfterDelete OnDelete Runs after an item is deleted (thrugh the delete r purge actins.) OnAfterDelete methds wuld be used t synchrnize with ther items r with external systems (e.g. remve a recrd frm ERP.) 2015 Aras Crpratin All Cpyrights Reserved. 27

28 OnBefreGet OnAfterGet OnGet Runs in place f the built-in delete actin. Neither OnBefreDelete nr OnAfterDelete events are called when using OnDelete. An OnDelete methd cmpletely replaces the built-in delete actin, and wuld typically be used fr federated items. The methd is expected t remve the apprpriate recrds in the database and frm a prper respnse. Runs befre a search. OnBefreGet methds are typically used t add additinal criteria t a search, based n business rules. Fr example, the methd might find the default lcatin f the user and add that lcatin as criteria fr the query. Runs after a search is executed, but befre the results are returned. OnAfterGet methds are cmmnly used t ppulate federated prperties. This might invlve perfrming calculatins n ther prperties r extracting data frm an external system. Once the value f the federated prperty is set, it appears t the client like any ther prperty. Runs in place f the built-in get actin. Neither OnBefreGet nr OnAfterGet events are called when using OnGet. An OnGet methd cmpletely replaces the built-in get actin, and wuld typically be used fr federated items. The methd is expected t retrieve the apprpriate recrds in the database and frm a prper AML respnse. OnBefreCpy OnAfterCpy Runs befre an item is cpied (via the cpy actin.) An OnBefreCpy methd might be used t cancel a cpy peratin that vilates a business rule. OnBefreLck OnAfterLck Runs befre an item is cpied (via the cpy actin.) OnAfterCpy methds can be used t set prperties f the new item created by the cpy. Runs befre an item is lcked (via the lck r edit actins) An OnBefreLck methd may be used t prevent an item frm being lcked based n business rules. Runs after an item is lcked (via the lck r edit actins.) OnAfterLck methds may be used t synchrnize lcks with ther items. OnBefreUnlck Runs befre an item is unlcked. An OnBefreUnlck methd may be used t prevent an item frm being unlcked based n business rules Aras Crpratin All Cpyrights Reserved. 28

29 OnAfterUnlck Runs after an item is unlcked. OnAfterUnlck methds may be used t synchrnize lcks with ther items. OnBefreVersin Runs befre an item is versined (thrugh the versin, update, edit r merge actins.) OnBefreVersin methds are typically used t cancel a versin peratin based n a business rule. OnAfterVersin Runs after an item is versined (thrugh the versin, update, edit r merge actins.) An OnAfterVersin methd might be used t set prperties f the new item versin. OnBefreMethd Runs befre Server Actin Methd. OnAfterMethd Runs after Server Actin Methd. OnGetKeyedName Runs when the system generates the keyed_name fr an item. Used t verride the standard lgic fr generating keyed names. 4.5 Client Events There are several Events available n the client side, which include: Frm Events Field Events Grid Events Item Type Events Item Actins Cntext Item The this keywrd cntext Object is an Item Object fr Item Actins. Hwever, the cntext Object is nt the Item Object fr Frm, Field, and Grid Events. The this cntext Object is the brwser dcument (DOM) Object fr the Frm and Grid Events and is the Field Object fr Field Events. The cntext Item Object fr Frm, Grid, and Field Events is the dcument.thisitem Object, which is an Item Object and shuld be used with the IOM API. Fr relatinship grid events use parent.thisitem, which is a pinter t the dcument.thisitem Object Aras Crpratin All Cpyrights Reserved. 29

30 4.5.2 Frm Events The Frm Events are the HTML page events; fr example, nlad, nunlad, nresize, nmusedwn, nmuseup, and thers (refer t the Frm Events List in Aras Innvatr fr the cmplete list f available events.) Yu bind yur Methd t the Frm Event using the Frm Tl. Select the Frm Event tab and add the event relatinships as shwn belw: Field Events Figure 1. The Field Events are the HTML field events; fr example, nselect, nclick, nchange, nblur, nfcus, and thers (refer t the Field Events List in Aras Innvatr fr the cmplete list f available events.) Yu bind yur Methd t the Field Event using the Frm Tl. Select the Field by clicking n it in the canvas area in frm Tl r frm the Fields grid in the upper left hand crner f the Frm Tl. Select the Field Event tab and add the event relatinships as shwn belw: 2015 Aras Crpratin All Cpyrights Reserved. 30

31 Figure Grid Events Grid Events are the events fr the grid cntrl, which is used in the Relatinships tab area fr tear ff Item windws. The grid events ccur n the rw (sectin ) and n the cell (sectin ) Like Server Events yu bind a Methd as the callback fr the event as the Grid Event relatinship n the RelatinshipType Item, and as the Grid Event relatinship n the Prperty Item. The Methd gets at least three arguments: relatinshipid, relatedid, gridapplet. The relatinshipid is the ID fr the relatinship Item fr the selected rw. The relatedid is the ID fr the related Item fr the selected rw. And the gridapplet is a handle t the grid cntrl bject. The relatedid maybe empty if there is n related Item fr the relatinship rw. The relatinshipid is als the ID fr the grid cntrl rw. Edit the RelatinshipType Item and add Grid Events relatinships as shwn belw: 2015 Aras Crpratin All Cpyrights Reserved. 31

32 Rw Events The rw events include: Figure 3. Event nselectrw ninsertrw ndeleterw Cmment Fires when the rw is selected. Fires when the rw is inserted. Fires when the rw is deleted Aras Crpratin All Cpyrights Reserved. 32

33 The Methd fr the event is called with three arguments: Argument Type Cmment relatinshipid String The ID fr the relatinship Item. This is als the selected rw ID fr the grid cntrl. relatedid String The ID fr the related Item. The relatedid maybe empty if there is n related Item fr the relatinship rw. gridapplet GridCntrl The handle t the grid cntrl Cell Events Edit the Prperty Item and add Event relatinships as shwn belw: The cell events include: Figure 4. Event neditstart neditfinish Cmment Fires when the cell gets fcus. Fires when the cell lses fcus Aras Crpratin All Cpyrights Reserved. 33

34 nchangecell Fires when the cell value changes. Default Search nsearchdialg The Methd fr the event is called with five arguments: Argument Type Cmment relatinshipid String The ID fr the relatinship Item. This is als the selected rw ID fr the grid cntrl. relatedid String The ID fr the related Item. The relatedid maybe empty if there is n related Item fr the relatinship rw. gridapplet GridCntrl The handle t the grid cntrl. prpertyname String The name f the Prperty fr the cell clumn selected. clnumber Integer The clumn psitin number in the grid Item Type Events Client Events that can be attached t an Item Type are triggered when user s UI actins generate a new Item. These events are triggered frm the client interface regardless f UI cntext n where in the GUI the new Item creatin was initialized. These events wuld be triggered universally frm the Main Menu, the TOC RMB menu, the Main Grid RMB menu, Relatinship Grid, etc. Fr Item Type new item creatin, 3 events have been implemented. One event is triggered befre a new Item is created; anther event is triggered after an Item has been created; third event replaces the standard client new Item lgic. Nte: nbefrenew: Methd runs prir t a new Item creatin. It has the ability t cancel subsequent client peratins (i.e., frm pening). It has ability t cancel creatin f new Item. This event is ften used t validate current cnditins and determine if it is k t create new Item. nafternew: Methd runs after a new Item is created. Subsequent standard client lgic is executed fllwing methd cmpletin (i.e., frm pening). Methd is passed new Item. This event is ften used t ppulate new item with data and pen custm dialgs. nnew: The methd replaces the standard new Item client behavir. This event is used in special situatins where slutin must maintain full cntrl ver the new Item creatin prcess. It is pssible that bth nbefrenew and nafternew events t be assigned t the same ItemType and therefre executed sequentially Aras Crpratin All Cpyrights Reserved. 34

35 Figure Item Actins and Server Event The Methds related t the ItemType via the Item Actin relatinship are called via the actin attribute and the Item.apply() methd and can be reviewed by searching the Item Actins Tab n the ItemType. The Methds related t the ItemType via the Server Event relatinship are called by the server as pre and pst event callbacks fr the primitive server actins: add, update, delete, and get. And can be reviewed by searching the Server Events Tab n the ItemType. The Generic Methds can be reviewed by searching the Methd Items Aras Crpratin All Cpyrights Reserved. 35

36 5 Actin Items An Actin Item is hw Methds are bund t the client User Interface. Actins prvide the hks fr invking Methds frm the Actin menu bar chice r frm the right muse cntext ppup menu. An Actin is invked n the client side but can call either a client r server side Methd. In bth cases the cntext Item must be defined. The item_query Prperty n the Actin Item is used t specify the query used t ppulate the cntext Item. This Prperty is f data_type="text" because it is actually an XSLT stylesheet. Simply put the item_query Actin Prperty drives the cntent fr the cntext Item fr the Actin Methds. The use f a XSLT stylesheet fr the item_query is cnsistent with hw Aras Innvatr sends ut Ntificatins fr Life Cycle prmtins bth n the State and n the Transitin, n Wrkflw Activities, and in the Reprt Tl. The cncept is the XSLT stylesheet is applied t the Item and the result is the AML query, which is used t get the cntext Item fr the Methd. This allws yu t basically turn an Item int a query fr the data yu want as the cntext Item fr the Methd. The default value fr the item_query Actin Prperty is: <Item type="{@type" id="{@id" actin="get" levels="0"/> Nte the use f the XSLT Attribute Substitutin fr the type and id attributes. If yu want all yur ld actins, created with Innvatr r earlier, that expect relatinships t wrk, use the fllwing query string: <Item type="{@type" id="{@id" actin="get" levels="1"/> The rules fr hw the cntent fr the cntext Item are defined belw fr bth client and server Methds. 5.1 Client Side Methd Rules If has cache Item and is dirty then it is the cntext Item regardless if there is an item_query stylesheet value. If has cache Item and is nt dirty and has item_query value then the stylesheet is applied against the cache Item and the result is the AML query t get the cntext Item fr the Methd. If has cache Item and is nt dirty and n item_query value then the cache Item is the cntext Item fr the Methd. If n cache Item and n item_query value then the temprary Item with nly the type and id attributes is the cntext Item fr the Methd. If n cache Item and has item_query value then a temprary Item is used cntaining nly the Item tag with the type and id attributes. The stylesheet fr the item_query is applied t the temprary Item and the result is used as the AML query fr the cntent fr the cntext Item fr the Methd. 5.2 Server Side Methd Rules Currently the server side autmatically gets the Item with levels="0" and ignres any extra Prperty tags passed frm the client request. This needs t be changed in rder t supprt mre granular cntext Items and t pass in cntext Item via the client request. The Actin needs t setup the Item fr the server side Methd request. This can range frm the dirty Item frm the client cache t nly the <Item> tag with its type and id attributes plus the actin attribute specifying the Methd name t run Aras Crpratin All Cpyrights Reserved. 36

37 T achieve backward cmpatibility with existing server side Methd lgic the cntext Item must be the Item frm a server pre-getitem call with levels="0". The server knws t d this when the same frmat fr the AML we pass tday is still passed, which is t put the ID fr the Item as a Prperty in the request nt as an attribute: <Item type="itemtype Name" actin="methd Name"> <id>itemid</id> </Item> The stylesheet fr the item_query value wuld be the fllwing, which cnstructs the AML frmat abve: <Item type="{@type"><id><xsl:value-f select="@id"/></id></item> If n cache Item and n item_query value then the temprary Item with the type attribute and the id is nested as a Prperty tag as shwn abve is passed as the request triggering the server t d the pre- GetItem levels="0" as tday and the result is the cntext Item fr the Methd. If has cache Item and is dirty and n item_query value then passes the dirty Item, which is the cntent fr the cntext Item fr the server Methd. If has item_query value but n cache Item then a temprary Item is used cntaining nly the Item tag with the type and id attributes. Plus the dgetitem="1" attribute is included, which frces the server t d the pre-getitem using this as its query criteria and its results is the cntent fr the cntext Item fr the server side Methd. If has cache Item and is nt dirty and has item_query value applies the stylesheet t the cached Item and pass that as the Item request. Plus the dgetitem="1" attribute is included, which frces the server t d the pre-getitem using AML passed as the query criteria and the results is the cntent fr the cntext Item fr the server side Methd. 5.3 Use Cases Client side - has cache Item is dirty Use Case Name: Summary: Precnditins: Basic Curse f Events: Client side has cache Item is dirty Invkes client side Item Methd and the cntent fr the cntext Item is the cached Item. 1. That an Item is selected and the type and id fr the selected Item is knwn by the client. 2. That the ItemType fr the selected Item has an "Item Actin" RelatinshipType and the Actin type="item" and lcatin="client". 1. User selected an Item. 2. Invkes the Actin by cntext menu pick r menu bar Actin menu pick. Exceptin Paths: 2015 Aras Crpratin All Cpyrights Reserved. 37

38 5.3.2 Client side - n cache Item - n item_query value Use Case Name: Summary: Precnditins: Basic Curse f Events: Exceptin Paths: Client side n cache Item n item_query value Invkes client side Item Methd and the nly criteria knwn is the type and id s the cntent fr the cntext Item is nly the Item tag with the type and id attributes. 1. That an Item is selected and the type and id fr the selected Item is knwn by the client. 2. That the ItemType fr the selected Item has an "Item Actin" RelatinshipType and the Actin type="item" and lcatin="client". 1. User selected an Item. 2. Invkes the Actin by cntext menu pick r menu bar Actin menu pick. The type r id is unknwn when the cnditin requires them t be knwn Client side - has cache Item nt dirty - n item_query value Use Case Name: Summary: Precnditins: Basic Curse f Events: Client side has cache Item nt dirty n item_query value Invkes client side Item Methd and the cntent fr the cntext Item is cached Item. 1. That an Item is selected and the type and id fr the selected Item is knwn by the client. 2. That the ItemType fr the selected Item has an "Item Actin" RelatinshipType and the Actin type="item" and lcatin="client". 1. User selected an Item. 2. Invkes the Actin by cntext menu pick r menu bar Actin menu pick. Exceptin Paths: 2015 Aras Crpratin All Cpyrights Reserved. 38

39 5.3.4 Client side - has cache Item nt dirty - has item_query value Use Case Name: Summary: Precnditins: Basic Curse f Events: Exceptin Paths: Client side has cache Item nt dirty has item_query value Invkes client side Item Methd and the cntent fr the cntext Item is the result frm a server request using the result f the XSLT transfrmatin f the cached Item with the item_query stylesheet as the AML query server request. 1. That an Item is selected and the type and id fr the selected Item is knwn by the client. 2. That the ItemType fr the selected Item has an "Item Actin" RelatinshipType and the Actin type="item" and lcatin="client". 1. User selected an Item. 2. Invkes the Actin by cntext menu pick r menu bar Actin menu pick. The item_query is nt a valid XSLT stylesheet Client side - n cache Item - has item_query value Use Case Name: Summary: Precnditins: Basic Curse f Events: Exceptin Paths: Client side n cache Item has item_query value Invkes client side Item Methd and the cntent fr the cntext Item is the result frm a server request using the result f the XSLT transfrmatin f a temprary Item that nly includes the type and id attributes with the item_query stylesheet as the AML query server request. 1. That an Item is selected and the type and id fr the selected Item is knwn by the client. 2. That the ItemType fr the selected Item has an "Item Actin" RelatinshipType and the Actin type="item" and lcatin="client". 1. User selected an Item. 2. Invkes the Actin by cntext menu pick r menu bar Actin menu pick. 1. The type r id is unknwn when the cnditin requires them t be knwn. 2. The item_query is nt a valid XSLT stylesheet Aras Crpratin All Cpyrights Reserved. 39

40 5.3.6 Server side - has cache Item is dirty Use Case Name: Summary: Precnditins: Basic Curse f Events: Server side has cache Item and is dirty Invkes server side Item Methd and the cntent fr the cntext Item is the cached Item passed as the request AML. 1. That an Item is selected and the type and id fr the selected Item is knwn by the client. 2. That the ItemType fr the selected Item has an "Item Actin" RelatinshipType and the Actin type="item" and lcatin="server". 1. User selects an Item. 2. Invkes the Actin by cntext menu pick r menu bar Actin menu pick. Exceptin Paths: Server side - n cache Item - n item_query value Use Case Name: Summary: Precnditins: Basic Curse f Events: Exceptin Paths: Server side n cache Item n item_query value Invkes server side Item Methd and the nly criteria knwn is the type and id. The AML request is the nested id tag style we pass tday, which tells the server t perfrm the pre-getitem with levels="0" and the result is the cntent fr the cntext Item. This is the same as we currently d tday. 1. That an Item is selected and the type and id fr the selected Item is knwn by the client. 2. That the ItemType fr the selected Item has an "Item Actin" RelatinshipType and the Actin type="item" and lcatin="server". 1. User selects an Item. 2. Invkes the Actin by cntext menu pick r menu bar Actin menu pick. The type r id is unknwn when the cnditin requires them t be knwn Aras Crpratin All Cpyrights Reserved. 40

41 5.3.8 Server side - has cache Item nt dirty - n item_query value Use Case Name: Summary: Precnditins: Basic Curse f Events: Server side has cache Item nt dirty n item_query value Invkes server side Item Methd and the AML request is the nested id tag style we pass tday, which tells the server t perfrm the pre- GetItem with levels="0" and the result is the cntent fr the cntext Item. This is the same as we currently d tday. 1. That an Item is selected and the type and id fr the selected Item is knwn by the client. 2. That the ItemType fr the selected Item has an "Item Actin" RelatinshipType and the Actin type="item" and lcatin="client". 1. User selects an Item. 2. Invkes the Actin by cntext menu pick r menu bar Actin menu pick. Exceptin Paths: Server side - has cache Item nt dirty - has item_query value Use Case Name: Summary: Precnditins: Basic Curse f Events: Exceptin Paths: Server side has cache Item nt dirty has item_query value Invkes server side Item Methd and the cntent fr the cntext Item is the result frm a server pre-getitem where the AML passed is the AML query, which is the result f the XSLT transfrmatin f the cached Item with the item_query stylesheet; plus the dgetitem="1" attribute is als set, which tells the server t d the pre-getitem using the request AML as the query, the results is the cntent fr the cntext Item. 1. That an Item is selected and the type and id fr the selected Item is knwn by the client. 2. That the ItemType fr the selected Item has an "Item Actin" RelatinshipType and the Actin type="item" and lcatin="server". 1. User selects an Item. 2. Invkes the Actin by cntext menu pick r menu bar Actin menu pick. The item_query is nt a valid XSLT stylesheet Aras Crpratin All Cpyrights Reserved. 41

42 Server side - n cache Item - has item_query value Use Case Name: Summary: Precnditins: Basic Curse f Events: Exceptin Paths: Server side n cache Item has item_query value Invkes server side Item Methd and the cntent fr the cntext Item is the result frm a server pre-getitem where the AML passed is the AML query, which is the result f the XSLT transfrmatin f a temprary Item that has nly the Item tag with the type and id attributes with the item_query stylesheet; plus the dgetitem="1" attribute is als set, which tells the server t d the pre-getitem passing its results as the cntent fr the cntext Item. 1. That an Item is selected and the type and id fr the selected Item is knwn by the client. 2. That the ItemType fr the selected Item has an "Item Actin" RelatinshipType and the Actin type="item" and lcatin="server". 1. User selected an Item. 2. Invkes the Actin by cntext menu pick r menu bar Actin menu pick. 1. The type r id is unknwn when the cnditin requires them t be knwn. 2. The item_query is nt a valid XSLT stylesheet Aras Crpratin All Cpyrights Reserved. 42

43 6 Aras Innvatr Methdlgy This sectin is a summary f the Aras Innvatr Methdlgy. Fllwing this methdlgy, helps yu build better quality Aras Innvatr business lgic mre quickly; plus it is easier t understand and maintain the cde. The AML is the language that drives the Aras Innvatr Server. AML dcuments cntain Items, Structure, and Lgic, s they are scripts. The Aras Innvatr Server is a message based system in that it accepts AML scripts as messages and returns AML messages. AML dcument, AML script, AML message all mean the same thing. The IOM is the Object API used t build and apply AML messages. Methds implement business lgic using the IOM API. Methds extend the Item Class when used as "Item Actin" relatinships n the ItemType, which simulates Object Oriented prgramming, where the ItemType is the Class and "Item Actin" relatinships t Methds are the Class methds. Methds are als generic arbitrary business lgic that can be called like a sub rutines frm ther Methds using the IOM Innvatr.applyMethd( ) methd. Methds fllw the Item Factries design pattern; they shuld return a new Item and nt side effect the cntext Item. Server Events are the exceptin because the purpse is t intercept and perate n the AML befre the server parses it, and befre the AML is returned t the client after the server parses it. S yu d mdify the cntext Item and return nthing. Implement changes/edits t the cntext Item in the OnBefre Event by altering the AML befre the server parses it. Refrain frm attempting t update the cntext Item after the server has already perated n it in the OnAfter Event. Use the OnAfter Events t update/include federated data in the respnse AML. Use the select, page, and pagesize attributes fr the AML queries t ptimize the perfrmance fr the request. Use the generic IOM methds t cnstruct the AML queries rather than cnvenience methds like getitemby_, getrelatinships(), r use the levels attribute because the cnvenience methds typically return far mre data than required impsing a perfrmance hit. The cntext Item is the keywrd this Object fr JavaScript and C#, and the Me Object fr VB.Net. The cntext Item fr Generic Methds is any XML yu want but it is highly recmmended that yu cntinue t use AML t represent yur data. This prvides the benefit f using the IOM t manage the input fr the Generic Methds. Attributes are used t pass cntrl switches t the Methd. Yu can invent yur wn because they are a simple way t pass meta-data t the Methd Aras Crpratin All Cpyrights Reserved. 43

44 7 Ckbk This sectin is a Ckbk f recipes t help yu slve cmmn tasks while develping Methds. The examples are shwn in JavaScript, C# and VB.Net when pssible. 7.1 Create an Aras Innvatr Object Yu need an Innvatr Object t return a newresult() r newerrr() Item. Technique There are basically tw ways t create a new Innvatr bject; by getting the Innvatr frm the Item bject r (nly in JavaScript) calling the Class cnstructr. JavaScript var myinnvatr = new Innvatr(); var myinnvatr = this.getinnvatr(); C# Innvatr myinnvatr = this.getinnvatr(); VB.Net Dim myinnvatr As Innvatr = Me.getInnvatr() 7.2 Create an Item Object Yu need an Item Object t submit a query r t add an Item. Technique There are basically tw ways t create a new Item Object; by calling the factry methds n the Item bject r Innvatr bject r (nly in JavaScript) calling the Class cnstructr. JavaScript var myitem = new Item(); var myitem = this.newitem(mytype,myactin); var myinnvatr = this.getinnvatr(); var myitem = myinnvatr.newitem(mytype,myactin); var myresult = myinnvatr.newresult(resulttext); var myerrr = myinnvatr.newerrr(errrmessage); C# Item myitem = this.newitem(mytype,myactin); Innvatr myinnvatr = this.getinnvatr(); Item myitem = myinnvatr.newitem(mytype,myactin); Item myresult = myinnvatr.newresult(resulttext); Item myerrr = myinnvatr.newerrr(errrmessage); 2015 Aras Crpratin All Cpyrights Reserved. 44

45 VB.Net Dim myitem As Item = Me.NewItem(myType,myActin) Dim myinnvatr As Innvatr = Me.getInnvatr() Dim myitem As Item = myinnvatr.newitem(mytype,myactin) Dim myresult As Item = myinnvatr.newresult(resulttext) Dim myerrr As Item = myinnvatr.newerrr(errrmessage) 7.3 Query fr an Item Yu want t query fr an Item that yu knw by id and type. Technique There are a few ways t get an Item when yu knw its id and type, the simplest being the Innvatr.getItemById() methd. Hwever, if yu need t be granular abut yur request then building the query using the IOM is required. This prvides the ability t include cntrls t limit the results and define the structure t be returned fr the Items fund. JavaScript var qryitem = this.newitem(mytype,"get"); qryitem.setid(myid); var results = qryitem.apply(); var myinnvatr = this.getinnvatr(); var results = myinnvatr.getitembyid(mytype, myid); C# Item qryitem = this.newitem(mytype,"get"); qryitem.setid(myid); Item results = qryitem.apply(); Innvatr myinnvatr = this.getinnvatr(); Item results = myinnvatr.getitembyid(mytype, myid); VB.Net Dim qryitem As Item = Me.NewItem(myType,"get") qryitem.setid(myid) Dim results As Item = qryitem.apply() Dim myinnvatr As Innvatr = Me.getInnvatr() Dim results As Item = myinnvatr.getitembyid(mytype, myid) 2015 Aras Crpratin All Cpyrights Reserved. 45

46 7.4 Query and iterate ver a set f Items Yu want t query fr the Items that match sme criteria and generate an HTML Table as the results. Technique There is n difference in setting up a query fr a single Item r fr many. Only the criteria define the set size returned. In this recipe yu create an Item and ppulate the query criteria, apply it, and iterating ver the Items returned prducing a HTML <TABLE> fragment. JavaScript var qryitem = this.newitem("part","get"); qryitem.setattribute("select","item_number,descriptin,cst"); qryitem.setprperty("cst", "100"); qryitem.setprpertycnditin("cst", "gt"); var results = qryitem.apply(); var cunt = results.getitemcunt(); var cntent = "<table>"; fr (var i=0; i<cunt; ++i) { var item = results.getitembyindex(i); cntent += "" + "<tr>" + "<td>" + item.getprperty("item_number") + "</td>" + "<td>" + item.getprperty("descriptin") + "</td>" + "<td>" + item.getprperty("cst") + "</td>" + "</tr>"; cntent += "</table>"; return cntent; C# Item qryitem = this.newitem("part","get"); qryitem.setattribute("select","item_number,descriptin,cst"); qryitem.setprperty("cst", "100"); qryitem.setprpertycnditin("cst", "gt"); Item results = qryitem.apply(); int cunt = results.getitemcunt(); int i; string cntent = "<table>"; fr (i=0; i<cunt; ++i) { Item item = results.getitembyindex(i); cntent += "" + "<tr>" + "<td>" + item.getprperty("item_number") + "</td>" + "<td>" + item.getprperty("descriptin") + "</td>" + "<td>" + item.getprperty("cst") + "</td>" + "</tr>"; cntent += "</table>"; Innvatr innvatr = this.getinnvatr(); return innvatr.newresult(cntent); 2015 Aras Crpratin All Cpyrights Reserved. 46

47 VB.Net Dim qryitem As Item = Me.NewItem("Part","get") qryitem.setattribute("select","item_number,descriptin,cst") qryitem.setprperty("cst", "100") qryitem.setprpertycnditin("cst", "gt") Dim results As Item = qryitem.apply() Dim cunt As Integer = results.getitemcunt() Dim i As Integer Dim cntent As String = "<table>" Fr i=0 t cunt - 1 Dim item As Item = results.getitembyindex(i) cntent += "" + _ "<tr>" + _ "<td>" + item.getprperty("item_number") + "</td>" + _ "<td>" + item.getprperty("descriptin") + "</td>" + _ "<td>" + item.getprperty("cst") + "</td>" + _ "</tr>" Next cntent += "</table>" Dim innvatr As Innvatr = Me.getInnvatr() return innvatr.newresult(cntent) 7.5 Query fr an Item and return its cnfiguratin Yu want t query fr an Item and return its cnfiguratin in the results. Technique T query fr an Item and retrieve its structure yu build the query as the structure yu want returned. Use the IOM methds t add the relatinships yu want and build the structure in the Item. The server returns the structure that fllws the request structure. This recipe illustrates several related cncepts tgether, which are hw t get a set f Items frm an Item and hw t iterate ver the set, plus hw t get the related Item frm the relatinship Item. JavaScript var innvatr = this.getinnvatr(); // Set up the query Item. var qryitem = this.newitem("part","get"); qryitem.setattribute("select","item_number,descriptin,cst"); qryitem.setid(myid); // Add the BOM structure. var bmitem = this.newitem("part BOM","get"); bmitem.setattribute("select","quantity,related_id(item_number,descriptin,c st)"); qryitem.addrelatinship(bmitem); // Perfrm the query. var results = qryitem.apply(); // Test fr an errr Aras Crpratin All Cpyrights Reserved. 47

48 if (results.iserrr()) { tp.aras.alerterrr("item nt fund: " + results.geterrrdetail()); return; // Get a handle t the BOM Items. var bmitems = results.getrelatinships(); var cunt = bmitems.getitemcunt(); // Create the results cntent. var cntent = "<table brder='1'>" + "<tr>" + "<td>part Number</td>" + "<td>descriptin</td>" + "<td>cst</td>" + "<td>quantity</td>" + "</tr>"; // Iterate ver the BOM Items. fr (var i=0; i<cunt; ++i) { // Get a handle t the relatinship Item by index. var bm = bmitems.getitembyindex(i); // Get a handle t the related Item fr this relatinship Item. var bmpart = bm.getrelateditem(); cntent += "<tr>" + "<td>" + bmpart.getprperty("item_number") + "</td>" + "<td>" + bmpart.getprperty("descriptin") + "</td>" + "<td>" + bmpart.getprperty("cst") + "</td>" + "<td>" + bm.getprperty("quantity") + "</td>" + "</tr>"; return cntent + "</table>"; C# Innvatr innvatr = this.getinnvatr(); // Set up the query Item. Item qryitem = this.newitem("part","get"); qryitem.setattribute("select","item_number,descriptin,cst"); qryitem.setid(myid); // Add the BOM structure. Item bmitem = this.newitem("part BOM","get"); bmitem.setattribute("select","quantity, related_id(item_number,descriptin,cst)"); qryitem.addrelatinship(bmitem); // Perfrm the query. Item results = qryitem.apply(); // Test fr an errr. if (results.iserrr()) { return innvatr.newerrr("item nt fund: " + results.geterrrdetail()); 2015 Aras Crpratin All Cpyrights Reserved. 48

49 // Get a handle t the BOM Items. Item bmitems = results.getrelatinships(); int cunt = bmitems.getitemcunt(); int i; // Create the results cntent. string cntent = "<table brder='1'>" + "<tr>" + "<td>part Number</td>" + "<td>descriptin</td>" + "<td>cst</td>" + "<td>quantity</td>" + "</tr>"; // Iterate ver the BOM Items. fr (i=0; i<cunt; ++i) { // Get a handle t the relatinship Item by index. Item bm = bmitems.getitembyindex(i); // Get a handle t the related Item fr this relatinship Item. Item bmpart = bm.getrelateditem(); cntent += "" + "<tr>" + "<td>" + bmpart.getprperty("item_number") + "</td>" + "<td>" + bmpart.getprperty("descriptin") + "</td>" + "<td>" + bmpart.getprperty("cst") + "</td>" + "<td>" + bm.getprperty("quantity") + "</td>" + "</tr>"; cntent += "</table>"; return innvatr.newresult(cntent); VB.Net Dim innvatr As Innvatr = Me.getInnvatr() ' Set up the query Item. Dim qryitem As Item = Me.newItem("Part","get") qryitem.setattribute("select","item_number,descriptin,cst") qryitem.setid(myid) ' Add the BOM structure. Dim bmitem As Item = Me.newItem("Part BOM","get") bmitem.setattribute("select","quantity,related_id(item_number,descriptin,c st)") qryitem.addrelatinship(bmitem) ' Perfrm the query. Dim results As Item = qryitem.apply() ' Test fr an errr. If results.iserrr() Then Return innvatr.newerrr(results.geterrrdetail()) End If 2015 Aras Crpratin All Cpyrights Reserved. 49

50 ' Get a handle t the BOM Items. Dim bmitems As Item = results.getrelatinships() Dim cunt As Integer = bmitems.getitemcunt() Dim i As Integer ' Create the results cntent. Dim cntent As String = "<table brder='1'>" + _ "<tr>" + _ "<td>part Number</td>" + _ "<td>descriptin</td>" + _ "<td>cst</td>" + _ "<td>quantity</td>" + _ "</tr>" ' Iterate ver the BOM Items Fr i = 0 T cunt - 1 ' Get a handle t the relatinship Item by index. Dim bm As Item = bmitems.getitembyindex(i) ' Get a handle t the related Item fr this relatinship Item. Dim bmpart As Item = bm.getrelateditem() cntent += _ "<tr>" + _ "<td>" + bmpart.getprperty("item_number") + "</td>" + _ "<td>" + bmpart.getprperty("descriptin") + "</td>" + _ "<td>" + bmpart.getprperty("cst") + "</td>" + _ "<td>" + bm.getprperty("quantity") + "</td>" + _ "</tr>" Next cntent += "</table>" Return innvatr.newresult(cntent) 2015 Aras Crpratin All Cpyrights Reserved. 50

51 7.6 Query using AML t cnstruct the query Yu want t perfrm a query using the AML t cnstruct the query criteria. Technique Create an Item Object but use the Item.ladAML() methd t ppulate the Item. JavaScript var innvatr = new Innvatr(); var qryitem = innvatr.newitem(); qryitem.ladaml( "<Item type='part' actin='get' select='item_number,descriptin,cst'>" + "<item_number cnditin='like'>1%</item_number>" + "<Relatinships>" + "<Item type='part BOM' actin='get' select='quantity'>" + "<quantity cnditin='gt'>1</quantity>" + "</Item>" + "</Relatinships>" + "</Item>" ); var resultitem = qryitem.apply(); if (resultitem.iserrr()) { tp.aras.alerterrr("item nt fund: " + resultitem.geterrrdetail()); return; var cunt = resultitem.getitemcunt(); fr (i=0; i<cunt; ++i) { var item = resultitem.getitembyindex(i); 7.7 Query fr the Item next prmtin states Yu want t get the next prmtin states fr an Item and use the states as the chices fr a drpdwn cntrl. Technique Use the item actin getitemnextstates t get the next state values. This recipe assumes there is a select input field n the frm fr us t ppulate with state values. HTML <select id="myselect"></select> JavaScript var results = dcument.thisitem.apply("getitemnextstates"); var nextstates = results.getitemsbyxpath('//item[@type="life Cycle State"]'); var cunt = nextstates.getitemcunt(); var Select = dcument.getelementbyid('myselect'); fr (var i=0; i<cunt; ++i) { 2015 Aras Crpratin All Cpyrights Reserved. 51

52 var item = nextstates.getitembyindex(i); var pt = dcument.createelement('ptin'); pt.text = item.getprperty('name'); Select.add(pt); 7.8 Query using relatinships as search criteria Yu want t search fr an Item using the relatinship and related Items as search criteria. In this recipe, we get the User Item that matches the Identity name as an Alias relatinship t the User Item. Technique The fllwing are sme key pints t understand when cnstructing an AML query: 1. Use the get actin n the relatinship Items t include it as search criteria. a. Withut the get actin the relatinship Item is ignred as search criteria. b. The relatinship Items are als returned. Currently there is n way t use relatinships as search criteria and nt return them in the results, as yu can with the related Item described belw. 2. Include the related_id prperty name in the select attribute fr the relatinship Item if yu want t return the related Item nested inside the related_id prperty in the results. <Item type="part BOM" select="quantity,related_id"/> Use () t include the select attribute value fr the related Item inside the select attribute fr the relatinship Item. <Item type="part BOM" select="quantity,related_id(item_number,descriptin)"/> 3. The select attribute fr the nested Item tag fr the related_id prperty has higher precedence ver the select value inside the () fr the relatinship's select attribute. 4. The get actin is nt required fr the nested Item tag fr the related_id prperty t include it as search criteria. These tw AML scripts are equivalent queries fr selecting the name prperty fr the related Item: <Item type="user" actin="get" select="first_name,last_name, "> <Relatinships> <Item type="alias" actin="get" select="related_id(name)"/> </Relatinships> </Item> <Item type="user" actin="get" select="first_name,last_name, "> <Relatinships> <Item type="alias" actin="get" select="related_id"> <related_id> <Item type="identity" actin="get" select="name"/> </related_id> </Item> </Relatinships> </Item> Clearly the first example is simpler and requires less cding (referring t the IOM lgic that wuld cnstruct the AML) and is the recmmended style when all yu require is specifying a select fr the related Item fr the query. But the secnd style pens the pprtunity t nw include additinal search criteria fr the related Item Aras Crpratin All Cpyrights Reserved. 52

53 AML <Item type="user" actin="get" select="first_name,last_name, "> <Relatinships> <Item type="alias" actin="get" select="related_id"> <!-- This get will limit rt Items t nly thse that match the relatinship criteria. The get actin is required therwise the criteria are ignred. T include the nested Item tag fr the related_id include the prperty name in the select attribute fr the relatinship Item. Can include the select attribute value fr the related Item inside () i.e. related_id(name) --> <related_id> <Item type="identity" actin="get" select="keyed_name"> <!-- This get has n effect and the search will wrk with r withut it. It is recmmended that yu include it because the AML parser may be stricter in the future. The select attribute ver rules the parent relatinships select. --> <name>larry Bird</name> </Item> </related_id> </Item> </Relatinships> </Item> JavaScript var innvatr = new Innvatr(); var qry = innvatr.newitem("user","get"); qry.setattribute("select","first_name,last_name, "); var alias = new Item("Alias","get"); alias.setattribute("select","related_id"); var identity = new Item("Identity","get"); identity.setattribute("select","name"); identity.setprperty("name", "Larry Bird"); alias.setrelateditem(identity); qry.addrelatinship(alias) ; var results = qry.apply(); if (results.iserrr()) { tp.aras.alerterrr(results.geterrrdetail()); return; 2015 Aras Crpratin All Cpyrights Reserved. 53

54 7.9 Add an Item cnfiguratin in ne transactin Yu want t add an Item cnfiguratin like a BOM as ne transactin. Technique Adding an Item cnfiguratin is dne by building the Item structure using the IOM methds. JavaScript var innvatr = new Innvatr(); var partitem = innvatr.newitem("part","add"); partitem.setprperty("item_number", " "); partitem.setprperty("descriptin", "Blah blah"); var bmitem = new Item("Part BOM","add"); bmitem.setprperty("quantity", "10"); var relateditem = new Item("Part","get"); relateditem.setprperty("item_number", " "); bmitem.setrelateditem(relateditem); partitem.addrelatinship(bmitem) ; var resultitem = partitem.apply(); if (resultitem.iserrr()) { tp.aras.alerterrr(resultitem.geterrrdetail()); return; Technique The fllwing is the same thing but uses the Item.ladAML() methd t ppulate the Item Object with AML text. JavaScript var innvatr = new Innvatr(); var partitem = innvatr.newitem(); partitem.ladaml( "<Item type='part' actin='add' >" + "<item_number> </item_number>" + "<descriptin>blah blah</descriptin>" + "<Relatinships>" + "<Item type='part BOM' actin='add'>" + "<quantity>10</quantity>" + "<related_id>" + "<Item type='part' actin='get'>" + "<item_number> </item_number>" + "</Item>" + "</related_id>" + "</Item>" + "</Relatinships>" + "</Item>" ); var resultitem = partitem.apply(); 2015 Aras Crpratin All Cpyrights Reserved. 54

55 if (resultitem.iserrr()) { tp.aras.alerterrr (resultitem.geterrrdetail()); return; 7.10 Add a Named Permissin Yu want t add a new named Permissin Item. Technique Use the Item Class Extended Methd set t add a new Named Permissin Item. JavaScript var innvatr = new Innvatr(); var permitem = innvatr.newitem("permissin","add"); permitem.setprperty("name", "AK Part Permissins"); setidentityaccess(permitem, "All Emplyees", "get", true); setidentityaccess(permitem, "CM", "get", true); setidentityaccess(permitem, "CM", "update", true); setidentityaccess(permitem, "CM", "delete", true); resultitem = permitem.apply(); if (resultitem.iserrr()) { tp.aras.alerterrr(resultitem.geterrrdetail()); return; functin setidentityaccess(item, identityname, permtype, accessstate) { var identity = item.newitem(); identity.settype("identity"); identity.setactin("get"); identity.setprperty("name", identityname); var access = item.newitem("access","add"); access.setprperty("can_"+permtype, (accessstate? "1" : "0")); access.setrelateditem(identity); item.addrelatinship(access); 7.11 Set a Private Permissin fr an Item Yu want t set a new private Permissin fr an Item. Technique Use the Item Class Extended Methd set t set a new private Permissin fr an Item. JavaScript // Set up the Part query var innvatr = new Innvatr; var qryitem = innvatr.newitem("part", "get"); qryitem.setattribute("select", "id,permissin_id"); qryitem.setattribute("expand", "1"); 2015 Aras Crpratin All Cpyrights Reserved. 55

56 qryitem.setattribute("levels", "1"); qryitem.setprpertycnditin("item_number", "like"); qryitem.setprperty("item_number", "123%"); // Run the query and check fr errrs var resultitem = qryitem.apply(); if (resultitem.iserrr()) { tp.aras.alerterrr(resultitem.geterrrdetail()); return; // Iterate ver the Items returned and add the private permissins fr each. var cunt = resultitem.getitemcunt(); fr (i=0; i<cunt; ++i) { var item = resultitem.getitembyindex(i); var permitem = item.getprpertyitem("permissin_id"); // Remve existing permissins first var accesses = permitem.getrelatinships("access"); fr (i=0; i<accesses.getitemcunt(); i++) { var access = accesses.getitembyindex(i); access.setactin("delete"); permitem.setprperty("name", permitem.getid()); setidentityaccess(permitem, "Cmpnent Engineering", "get", true); setidentityaccess(permitem, "CM", "get", true); setidentityaccess(permitem, "CM", "update", true); // Grant access t the current user's alias identity var myalias = innvatr.newitem("alias","get"); myalias.setprperty("surce_id", inn.getuserid()); myalias = myalias.apply(); var aliasid = myalias.getitembyindex(0).getprperty("related_id"); var aliasname = innvatr.getitembyid("identity",aliasid).getprperty("name"); setidentityaccess(permitem, aliasname, "get", true); item.setactin("edit"); resultitem = item.apply(); if (resultitem.iserrr()) { tp.aras.alerterrr(resultitem.geterrrdetail()); functin setidentityaccess(item, identityname, permtype, accessstate) { var identity = item.newitem(); identity.settype("identity"); identity.setactin("get"); identity.setprperty("name", identityname); var access = item.newitem("access","add"); access.setprperty("can_"+permtype, (accessstate? "1" : "0")); access.setrelateditem(identity); item.addrelatinship(access); 2015 Aras Crpratin All Cpyrights Reserved. 56

57 7.12 Apply a Generic Methd Yu want t write Generic Methds that can be used as subrutines fr ther Methds. Technique Use the Innvatr.applyMethd() methd t apply Generic Methds. The fllwing examples assume a server-side methd named "Reverse String" exists, and that it returns a result item cntaining the reversed cntents f the <string> tag. JavaScript var inn = this.getinnvatr(); var results = inn.applymethd("reverse String", "<string>abc</string>"); return results.getresult(); // returns "cba" C# Innvatr inn = this.getinnvatr(); Item results = inn.applymethd("reverse String", "<string>abc</string>"); // Return a result item with "cba" as the cntents f the Result tag return inn.newresult(results.getresult()); VB.Net Dim inn As Innvatr = Me.getInnvatr() Dim results As Item = inn.applymethd("reverse String", "<string>abc</string>") ' Return a result item With "cba" As the cntents f the Result tag Return inn.newresult(results.getresult()) 7.13 Need t Save text t a File Yu want t save text t a file. Technique Use the File and StreamWriter namespaces t write t a text file. C# Innvatr myinnvatr = this.getinnvatr(); string path = CCO.Server.MapPath("temp/yy.txt"); try { if (File.Exists(path)) File.Delete(path); StreamWriter sw = File.CreateText(path); sw.write(this.dm.innerxml); sw.clse(); catch (Exceptin e) { return myinnvatr.newerrr(e.message); return myinnvatr.newresult("k"); 2015 Aras Crpratin All Cpyrights Reserved. 57

58 7.14 Need t Send frm a Methd Yu want t send an message frm either server r client side Methd. Technique Use Aras.IOM.Item. (mail_item, idnt_item) methd t send t a particular Innvatr s identity. Nte: Innvatr s identity culd be a grup f peple in which case the is sent t all f them. C#... // It s assumed here that required identity (item f type Identity ) // has already btained (see ther examples n hw t perfrm get // requests t Innvatr server using IOM). Same abut item f type // User that represents the persn wh sends the ( frmuser ). Item idnt =... Item frmuser =... // It s assumed in the sample that this represents an item f // type Part. ${Item/item_number in the message is a parameter // that represents the XPath t the prperty item_number f // item f type Part; this parameter will be substituted n // this.item_number befre the is sent. Nte that bth // subject and bdy f the item culd be parameterized. // This mechanism allws t created parameterized templates // (items f type Message ) that culd be saved // in Innvatr and used fr sending s with cncrete cntent // when required. string subject = "Part prmtin ntificatin"; string bdy part ${Item/item_number has been prmted"; // In this particular example instead f getting a ready template // frm the server a new item f type Message is created Item _msg = this.newitem(" Message"); _msg.setprperty("subject", subject); _msg.setprperty("bdy_plain", bdy); _msg.setprpertyitem("frm_user", frmuser); // Finally send the if( this. ( _msg, idnt ) == false ) { // Errr handling Aras Crpratin All Cpyrights Reserved. 58

59 7.15 Need t Add an UI Cntrl Yu want t add ne f new DOJO cntrls t a page. Technique In HTML cde use the DOJO cntrl name (e.g. GridCntainer in the cde sample belw), the special <td> tag and apprpriate cntrl event handlers t run the cntrl n the page. Make sure that all the event handlers fr the cntrl are placed in HTML cde abve the <td> tag: HTML Cde <script type="text/javascript" src="../javascript/include.aspx?classes=scriptset2"></script> <script type="text/javascript" src="../javascript/include.aspx?classes=xmldcument"></script> <script type="text/javascript" src="../javascript/include.aspx?classes=/dj.js" data-dj-cnfig="isdebug: false, parseonlad: false, baseurl:'../javascript/dj'"></script> <script> var gridcntrl = null; var gridxml = '' + '<table>' + ' <thead>' + ' <th align="c">name</th>' + ' </thead>' + ' <clumns>' + ' <clumn width="130" rder="0" />' + ' </clumns>' + ' <tr>' + ' <td>test</td>' + ' </tr>' + '</table>'; windw.addeventlistener("domcntentladed", functin () { clientcntrlsfactry.createcntrl("aras.client.cntrls.public.gridcntaine r", {id: "grid", cnnectid: "gridtd", functin(cntrl) { gridcntrl = grid = cntrl; clientcntrlsfactry.n(grid, { "gridclick": nclick, "gridkeypress": nkeypressed, "grideditcell": OnEditCell, "gridmenuclick": nmenuclick, "gridmenuinit": InitMenu, "griddubleclick": ndubleclick ); gridcntrl.delimeter=" "; gridcntrl.initxml(gridxml); 2015 Aras Crpratin All Cpyrights Reserved. 59

60 ); ); functin nclick(rw, cl) { return; functin nkeypressed(kev) { return; functin OnEditCell(event, rw, cl) { return; functin nmenuclick(menuchice) { return; functin InitMenu(rw, cl) { return; functin ndubleclick(rid) { return; </script> <table> <tr> <td style="width:300px; height: 300px;" valign="tp" id="gridtd"> </td> </tr> </table> 2015 Aras Crpratin All Cpyrights Reserved. 60

61 7.16 Need fr Speed ApplySQL Yu want t query the DB directly bypassing Innvatr lgic t get the data faster. Technique Use the Innvatr.applySQL( ) methd t submit SQL direct t the database. The frmat f the xml returned by the Innvatr.applySQL( ) where passed SQL statement is a select statement is the fllwing: <SOAP-ENV:Envelpe xmlns:soap-env=...> <SOAP-ENV:Bdy> <ApplySQLRespnse> <Item> <A>aval</A> <B>bval</B>. </Item> <Item> </Item> </ApplySQLRespnse> </SOAP-ENV:Bdy> </SOAP-ENV:Envelpe> In case executed SQL statement desn t return a recrd set (e.g. update [table] ), the returned AML either cntains a <Fault> if SQL statement failed r lks like this: <SOAP-ENV:Envelpe xmlns:soap-env=...> <SOAP-ENV:Bdy> <ApplySQLRespnse> OK </ApplySQLRespnse> </SOAP-ENV:Bdy> </SOAP-ENV:Envelpe> This recipe returns the XML frm the applysql() methd and frms HTML fr a table t display the data. C# Innvatr myinnvatr = this.getinnvatr(); Item results = myinnvatr.applysql( "select lgin_name,first_name,last_name, " + "frm [user] " + "rder by last_name,first_name"); string cntent = "" + "<style type='text/css'>" + "table {backgrund:#000000;" + "th {fnt:bld 10pt Verdana; backgrund:#0000ff; clr:#ffffff;" + "td {fnt:nrmal 10pt Verdana; backgrund:#ffffff;" + "captin {fnt:bld 14pt Verdana; text-align:left;" + "</style>" + "<table id='tbl' brder='0' cellspacing='1' cellpadding='2' datasrc='#itemdata'>" + "<captin>user Directry</captin>" + "<thead>" Aras Crpratin All Cpyrights Reserved. 61

62 "<tr>" + "<th>lgin Name</th>" + "<th>first Name</th>" + "<th>last Name</th>" + "<th> </th>" + "</tr>" + "</thead>" + "<tbdy>"; int ucunt = results.getitemcunt(); fr (int i=0; i<ucunt; i++) { Item user = results.getitembyindex( i ); cntent += "<tr><td>" + user.getprperty( "lgin_name", "" ) + "</td>"; cntent += "<td>" + user.getprperty( "first_name", "" ) + "</td>"; cntent += "<td>" + user.getprperty( "last_name", "" ) + "</td>"; cntent += "<td>" + user.getprperty( " ", "" ) + "</td></tr>"; cntent += "" + "</tbdy>" + "</table>"; return myinnvatr.newresult(cntent); 7.17 Need a callback fr a Relatinships Grid Rw Event Yu want t call a client side Methd when the Relatinships Grid rw is selected t deselect the rw if it is nt a new relatinship rw. Technique Add the Grid Event relatinship t a Methd as the callback fr the OnSelectRw event. Figure Aras Crpratin All Cpyrights Reserved. 62

63 The Methd gets three arguments: relatinshipid, relatedid and gridapplet. The relatinshipid is the ID fr the relatinship Item fr the selected rw. The relatedid is the ID fr the related Item fr the selected rw. The gridapplet is a handle t the grid cntrl bject. The relatinshipid is als the ID fr the grid cntrl rw. This recipe calls the gridapplet Deselect() methd if the relatinship Item fr the selected rw if the relatinship has nt been mdified. JavaScript // The rw ID is the same as the relatinship ID var rwid = gridapplet.getselectedid(); // Find the relatinship item and exit if it's nt fund var thisitem = parent.thisitem; var xpath = "Relatinships/Item[@id='" + rwid + "']"; var relitem = thisitem.getitemsbyxpath(xpath); if (relitem.getitemcunt() == 1) { relitem = relitem.getitembyindex(0); else { return; // Check the isdirty attribute t see if the relatinship has been mdified var isdirty = (relitem.getattribute("isdirty") == "1"); if (!isdirty) { gridapplet.deselect(); 7.18 Need a callback fr a Relatinships Grid Cell Event Yu want t call a client side Methd when the Relatinships Grid cell is selected t blur the cell and prevent editing the cell value. Technique Add the Event relatinship t a Prperty as the callback fr the OnEditCell event. Figure Aras Crpratin All Cpyrights Reserved. 63

64 The Methd gets five arguments: relatinshipid, relatedid, prpertyname, clnumber, gridapplet The prpertyname is the name f the Prperty fr the cell clumn selected, and clnumber is the clumn psitin number in the grid. Simple return false and this blurs the grid cell. JavaScript // Get the current value f the cell var cellvalue = gridapplet.getcellvalue(relatinshipid,clnumber); // If the cell already has a value, disallw editing if (cellvalue!== "") { return false; 7.19 Shw relatinships in a Grid cntrl n the Frm Yu want t shw the relatinships fr the cntext Item in a Grid cntrl n the Item Frm. Technique Add an HTML Field (psitined at Pint (300,10) in the cde sample belw) and insert an HTML cde than defines the <div>tag t hld the dynamically ppulated grid and the JavaScript t get the ppulating grid relatinships. HTML Field cde <div id="gridtd" style="width: 400px; height: 500px;"></div> <script type="text/javascript"> var mycunt = 0; var gridcntrl; clientcntrlsfactry.createcntrl("aras.client.cntrls.public.gridcntaine r", {id: "grid", cnnectid: "gridtd", canedit_experimental: functin () { return false;, functin(cntrl){ gridcntrl = cntrl; clientcntrlsfactry.n(gridcntrl, { "gridclick": functin (rwid, clumn) { alert("rwid:" + rwid + ", cl:" + clumn); ); fillgrid(); ); functin fillgrid() { var item = dcument.thisitem; // Get the relatinships var qry = item.newitem("part BOM", "get"); qry.setattribute("select", "quantity,related_id(item_number,name,cst)"); qry.setprperty("surce_id", item.getid()); var results = qry.apply(); if (results.getitemcunt() < 0) { tp.aras.alerterrr(results.geterrrdetail()); return; // Ppulate the grid with the results. ppulategrid(item, results); 2015 Aras Crpratin All Cpyrights Reserved. 64

65 functin ppulategrid(item, results) { var prpnamearr = new Array("item_number", "name", "cst"); var gridxml = "<table editable='false' draw_grid='true'>" + "<clumns>" + "<clumn width='30%' rder='0' align='left' />" + "<clumn width='40%' rder='1' align='left' />" + "<clumn width='15%' rder='2' align='right' />" + "<clumn width='15%' rder='3' align='right' />" + "</clumns>" + "<thead>" + "<th>part Number</th>" + "<th>name</th>" + "<th>cst</th>" + "<th>quantity</th>" + "</thead>" + "</table>"; var inn = item.getinnvatr(); var griddm = inn.newxmldcument(); griddm.ladxml(gridxml); var tablend = griddm.selectsinglende("/table"); var c = results.getitemcunt(); fr (var i=0; i<c; ++i) { var bm = results.getitembyindex(i); var part = bm.getrelateditem(); var trnd = griddm.createelement("tr"); trnd.setattribute("id", bm.getid()); var tdnd; fr (var j=0; j<prpnamearr.length; j++) { tdnd = griddm.createelement("td"); tdnd.text = part.getprperty(prpnamearr[j]);+ trnd.appendchild(tdnd); tdnd = griddm.createelement("td"); tdnd.text = bm.getprperty("quantity"); trnd.appendchild(tdnd); tablend.appendchild(trnd); gridcntrl.initxml(griddm.xml); </script> 2015 Aras Crpratin All Cpyrights Reserved. 65

66 7.20 Open the relatinships in an Excel Dcument Yu want t pen the relatinships fr the cntext Item in an Excel dcument utside the Frm. Technique Using the Frm Tl we add an HTML Field t the Frm, which we use t insert the HTML and JavaScript cde fr displaying the Excel dcument fr the "My BOM" relatinships fr the dcument.thisitem cntext Part Item. Add a HTML Field and insert the fllwing cde, which defines a <buttn> tag t call the JavaScript cde t get the relatinships t ppulate the cntrl. Nte: Nte: The use f Excel autmatin is heavily dependent n the client security settings, and may nt wrk in all envirnments. The use f the ActiveX bject is nly supprted in Internet Explrer HTML Field cde <buttn nclick="penexcel()">open Excel Dcument</buttn> <script language="javascript"> functin MyOnladHandler() { if (!dcument.thisitem) { return; var item = dcument.thisitem; var qry = item.newitem('part BOM','get'); qry.setattribute('select','quantity,related_id(item_number,name,cst)'); qry.setprperty('surce_id', item.getid()); tp.results = qry.apply(); functin penexcel() { if (! dcument.thisitem) return; var item = dcument.thisitem var excel = new ActiveXObject("Excel.Applicatin"); excel.visible = true; var wrkbk = excel.wrkbks.add(); var sheet = wrkbk.activesheet; // Add the cntext Item t the Excel sheet. sheet.cells(1,1).value = "Part Number"; sheet.cells(2,1).value = "Descriptin"; sheet.cells(3,1).value = "Cst"; sheet.cells(1,2).value = item.getprperty('item_number'); sheet.cells(2,2).value = item.getprperty('name'); sheet.cells(3,2).value = item.getprperty('cst'); ppulateexcel(item, tp.results, sheet, 5); functin ppulateexcel(item, results, sheet, rw) { sheet.cells(rw,1).value = "Part Number"; sheet.cells(rw,2).value = "Descriptin"; sheet.cells(rw,3).value = "Cst"; sheet.cells(rw++,4).value = "Quantity"; var c = results.getitemcunt(); fr (var i=0; i<c; ++i) { 2015 Aras Crpratin All Cpyrights Reserved. 66

67 var bm = results.getitembyindex(i); var part = bm.getrelateditem(); sheet.cells(i+rw,1).value = part.getprperty('item_number'); sheet.cells(i+rw,2).value = part.getprperty('name'); sheet.cells(i+rw,3).value = part.getprperty('cst'); sheet.cells(i+rw,4).value = bm.getprperty('quantity'); sheet.range("a1:d1").entireclumn.autfit(); windw.attachevent("nlad", MyOnladHandler); </script> 7.21 Want the Identities fr the User Yu want t get the Identity ID's fr the User. Technique Use the classic Aras Innvatr API tp.aras.getidentitylist() methd, which returns a cmma delimited string f ID's. Nte: The classic API will eventually be eliminated and this methd will becme available n the IOM Innvatr bject as Innvatr.getIdentityList(). JavaScript // This will get an array f identity IDs frm the client cache var myidentityids = tp.aras.getidentitylist().split(','); 7.22 Want a field t be either a sequence r user entered value Yu want t enable a field n the frm t be a sequence value r allw the user t enter a value. Technique Use the classic Aras Innvatr API tp.aras.getnetsequence() methd, which returns the next sequence value frm the server. Nte: The classic API will eventually be eliminated and this methd will becme available n the IOM Innvatr bject as Innvatr.getNetSequence(). Using the Frm Tl we add an HTML Field t the Frm, which we use t insert the HTML and JavaScript cde fr t prvide the buttn t get the next sequence value and update the Field value and client cache Aras Crpratin All Cpyrights Reserved. 67

68 HTML Field cde <a href="javascript:getnextnumber();"> <img src="../images/sequence.svg" brder="0" style="max-width: 20px; maxheight: 20px;"> </a> <script> functin getnextnumber() { // Get the next sequence value. var seq = tp.aras.getnextsequence("","default Part"); // This will update the client cache with the new value. handleitemchange("item_number", seq); </script> 7.23 Want t Vault a File Yu want t save a Dcument with an attached File Technique Use the IOM newitem() and attachphysicalfile() methds t create an Item f type File and set up the request t be submitted t the Vault Server. JavaScript // Create the Dcument item var dcitem = this.newitem("dcument","add"); dcitem.setprperty("item_number","123"); // Create the File item and set the path t the file. var fileitem = this.newitem("file","add"); fileitem.setprperty("filename","my Dcument.dc"); fileitem.attachphysicalfile("c:\\my Dcument.dc"); // Create the relatinship between the Dcument and File var relitem = this.newitem("dcument File","add"); dcitem.addrelatinship(relitem); relitem.setrelateditem(fileitem); var results = dcitem.apply(); if (results.iserrr()) { tp.aras.alerterrr(results.geterrrdetail()); else { // Shw the new Dcument tp.aras.uishwitemex(results.getitembyindex(0).nde, 'tab view', true); 2015 Aras Crpratin All Cpyrights Reserved. 68

69 7.24 Want t get an existing Vaulted File and save it with a new Dcument Yu want t get an existing File frm the Vault and attach it t a new Dcument Technique This is similar t the last recipe, but uses the getitembykeyedname() methd t get an existing File Item and cpyasnew() t create it as a new File Item. JavaScript // Create the Dcument item var dcitem = this.newitem("dcument","add"); dcitem.setprperty("item_number","456"); // Get the File item var innvatr = this.getinnvatr(); var fileitem = innvatr.getitembykeyedname("file","my Dcument.dc"); if (fileitem.iserrr()) { tp.aras.alerterrr(fileitem.geterrrdetail()); return; // Duplicate File Item as files shuld be 1 t 1 var newfile = fileitem.apply("cpyasnew"); // Create the relatinship between the Dcument and File var relitem = this.newitem("dcument File","add"); dcitem.addrelatinship(relitem); relitem.setrelateditem(newfile); var results = dcitem.apply(); if (results.iserrr()) { tp.aras.alerterrr(results.geterrrdetail()); else { // Shw the new Dcument tp.aras.uishwitemex(results.getitembyindex(0).nde, 'tab view', true); 7.25 Want t pen a Vaulted File in Wrd Yu want t pen an existing File frm the Vault in Wrd. Technique We first checkut the file frm the vault t ur lcal drive and then pen the file in Wrd. The fllwing cde can be placed in a client side Methd and called via a generic Actin with target='nne' s that nly the Wrd windw is actually pened. Nte: The use f the ActiveX bject is nly supprted in Internet Explrer JavaScript // Prmpt the user fr the file name and retrieve the File item var dcname = prmpt("enter the Dcument Name:",""); var innvatr = this.getinnvatr(); var dcitem = innvatr.newitem("dcument","get"); 2015 Aras Crpratin All Cpyrights Reserved. 69

70 dcitem.setprperty("keyed_name",dcname); var relitem = innvatr.newitem("dcument File","get"); relitem.setattribute("select","related_id(keyed_name)"); dcitem.addrelatinship(relitem); dcitem = dcitem.apply(); if (dcitem.iserrr()) { tp.aras.alerterrr("dcument Nt Fund: " +dcitem.geterrrdetail()); return; var flder = tp.aras.getwrkingdir(); var results, filename; if(dcitem.getrelatinships().getitemcunt() > 0) { results = dcitem.getrelatinships().getitembyindex(0).fetchfileprperty("related_id",f lder+"\\", 0); filename = dcitem.getrelatinships().getitembyindex(0).getrelateditem().getprperty("ke yed_name"); if (results.iserrr()) { tp.aras.alerterrr("unable t retrieve the file frm the vault"); return; // Open the file in Wrd. try { var wrd = new ActiveXObject("Wrd.Applicatin"); wrd.visible = true; wrd.dcuments.pen(flder + "\\" + dcname); catch(e) { tp.aras.alerterrr("unable t launch Wrd. File saved as: "+flder + "\\" + filename); return; 2015 Aras Crpratin All Cpyrights Reserved. 70

71 7.26 Need t reject an Item Prmte Yu want t reject an Item Prmte if a value f Prperty is in valid. Technique Use the Pre Server Methd n the Life Cycle Transitin t call a server side Methd t validate the Item befre it is prmted and if invalid rejects the Prmte by returning an Errr Item. C# Figure 8. Innvatr innvatr = this.getinnvatr(); if (Cnvert.TDecimal(this.getPrperty("cst")) > 500) { Item errr = innvatr.newerrr("errr prmting: Item csts mre than $500.00"); return errr; return this; VB.Net Dim innvatr As Innvatr = Me.getInnvatr() If (CDec(Me.getPrperty("cst")) > 500) Then Dim Err As Item = innvatr.newerrr("errr prmting: Item csts mre than $500.00") Return Err End If 2015 Aras Crpratin All Cpyrights Reserved. 71

72 7.27 Hw t build XML fr grid <table> Tag The <table> tag has the fllwing attributes. <thead> Tag The <thread> tag defines the header. <th> Tag The same as <td> tag. See belw. <clumns> Tag The <clumns> tag has n attributes. Cntains <clumn> tags <clumn> Tag The <clumn> tag defines grid clumn. Attribute Type Cmments width Integer Width in pixels. Align String Text alignment. Order Integer The clumn rder. Edit String bginvert Blean Invert backgrund clr f selected cell frm this clumn. Srt String NOSORT NUMERIC DATE inputfrmat clname lcale String String String <inputrw> Tag The <inputrw> tag defines the input rw, has n attributes, and cntains <td> tags. has attribute visible. <tr> Tag The <tr> tag defines a rw. Cntains <td>, <tr>, and <userdata> tags. Attribute Type Cmments id String Rw ID Aras Crpratin All Cpyrights Reserved. 72

73 <td> Tag The <td> tag defines the cell. Attribute Type Cmments fnt String Fnt. textclr String Set the fregrund clr. bgclr String Set the backgrund clr. link ftd css String String String <userdata> Tag The <userdata> tag defines user data fr the rw. Attribute Type Cmments key String Key fr the value. value String The value. <list> Tag The <list> tag defines a list and cntains <listitem> tags. Attribute Type Cmments id String The ID fr the list. <listitem> Tag The <listitem> tag defines the item fr the list. Attribute Type Cmments label String The label fr the list item. value String The value fr the list item Aras Crpratin All Cpyrights Reserved. 73

74 7.28 Hw t build XML fr a Menu <menuapplet> Tag The <menuapplet> tag cntains <menubar> tags. Attribute Type Cmments shw String The identifier f visible tlbar. If this parameter is absent, first menubar frm list is visible. <menubar> Tag The <menubar> tag cntains <item>, <checkitem>, and <separatr> tags. Attribute Type Cmments id String <item> Tag The <item> tag defines a menu item. <checkitem> Tag The <checkitem> tag defines a tggle buttn menu item. <seperatr> Tag The <seperatr> tag defines a separatr fr the menu Hw t handle multilingual prperties Yu want t prgrammatically get/set multilingual string prperties Technique Use Item.setAttribute("language","*") t get all language values and Item.setPrperty(myPrperty,value,lang) t set specific language values. JavaScript var inn = this.getinnvatr(); // Add a new List with multilingual Value labels var listitem = this.newitem("list","add"); listitem.setprperty("name","numbers"); var valueitem = listitem.createrelatinship("value","add"); valueitem.setprperty("value","1"); valueitem.setprperty("label","one","en"); valueitem.setprperty("label","ein","de"); var valueitem2 = listitem.createrelatinship("value","add"); valueitem2.setprperty("value","2"); 2015 Aras Crpratin All Cpyrights Reserved. 74

75 valueitem2.setprperty("label","tw","en"); valueitem2.setprperty("label","zwei","de"); var resultitem = listitem.apply(); if (resultitem.iserrr()) { return inn.newerrr("errr adding List: " + resultitem.geterrrdetail()); // Retrieve the List with labels in bth English and German listitem = this.newitem("list","get"); listitem.setprperty("name","numbers"); valueitem = listitem.createrelatinship("value","get"); valueitem.setattribute("language","en,de"); resultitem = listitem.apply(); if (resultitem.iserrr()) { return inn.newerrr("errr retrieving List: " + resultitem.geterrrdetail()); VB.Net Dim inn As Innvatr = Me.getInnvatr() ' Add a New List With multilingual Value labels Dim listitem As Item = Me.newItem("List","add") listitem.setprperty("name","numbers") Dim valueitem As item = listitem.createrelatinship("value","add") valueitem.setprperty("value","1") valueitem.setprperty("label","one","en") valueitem.setprperty("label","ein","de") Dim valueitem2 As Item = listitem.createrelatinship("value","add") valueitem2.setprperty("value","2") valueitem2.setprperty("label","tw","en") valueitem2.setprperty("label","zwei","de") Dim resultitem As Item = listitem.apply() If (resultitem.iserrr()) Then Return inn.newerrr("errr adding List: " + resultitem.geterrrdetail()) End If ' Retrieve the List with labels In bth English And German listitem = Me.newItem("List","get") listitem.setprperty("name","numbers") valueitem = listitem.createrelatinship("value","get") valueitem.setattribute("language","en,de") resultitem = listitem.apply() If (resultitem.iserrr()) Then Return inn.newerrr("errr retrieving List: " + resultitem.geterrrdetail()) End If Return inn.newresult("k") 7.30 Hw t handle date prperties Yu want t prgrammatically get/set date prperties 2015 Aras Crpratin All Cpyrights Reserved. 75

76 Technique Cnvert date values t "yyyy-mm-ddthh:mm:ss" frmat befre setting the prperty JavaScript // Get yesterday's date var mydate = new Date(); mydate.setdate(mydate.getdate()-1); // Find all methds edited in the past 24 hurs var myitem = this.newitem("methd","get"); myitem.setattribute("select","name"); myitem.setprperty("mdified_n",datefrmat(mydate)); myitem.setprpertyattribute("mdified_n","cnditin","gt"); myitem = myitem.apply(); // Lp thrugh the returned methds and return the list var methdlist = new String(""); fr (var i=0; i<myitem.getitemcunt(); i++) { methdlist += myitem.getitembyindex(i).getprperty("name","") + ", "; tp.aras.alerterrr("the fllwing methds were mdified in the past 24 hurs: "+methdlist.substr(0,methdlist.length-2)); functin datefrmat(d) { var datestring = d.getfullyear()+"-"; datestring += pad(d.getmnth()+1)+"-"; datestring += pad(d.getdate())+"t"; datestring += pad(d.gethurs())+":"; datestring += pad(d.getminutes())+":"; datestring += pad(d.getsecnds()); return datestring; functin pad(x) { return (x<10)? "0"+x : ""+x; VB.Net ' Get yesterday's date Dim mydate As Date = Nw.AddDays(-1) ' Find all methds edited in the past 24 hurs Dim myitem As Item = Me.newItem("Methd","get") myitem.setattribute("select","name") myitem.setprperty("mdified_n",mydate.tstring("yyyy-mm-ddthh:mm:ss")) myitem.setprpertyattribute("mdified_n","cnditin","gt") myitem = myitem.apply() ' Lp thrugh the returned methds and return the list Dim methdlist As String = "" Dim i As Integer = 0 Fr i = 0 T myitem.getitemcunt() - 1 methdlist += myitem.getitembyindex(i).getprperty("name","") + ", " Next i 2015 Aras Crpratin All Cpyrights Reserved. 76

77 Dim inn As Innvatr = Me.getInnvatr() Return inn.newerrr("the fllwing methds were mdified In the past 24 hurs: "+Left(methdList,methdList.Length-2)) 7.31 Hw t pass values frm nbefrex t nafterx events Yu want t pass sme value frm an nbefre (i.e. nbefreupdate) event t an nafter (i.e. nafterupdate) event fr data prcess handling Technique Use the built in functin t add a variable, read a variable and remve a variable frm the RequestState. This sample determines if there was a change made t the Name prperty f Part. C# OnBefreUpdate event //Get Part Name befre change Innvatr inn = this.getinnvatr(); Item mypart = inn.newitem("part","get"); mypart.setid(this.getid()); mypart.setattribute("select","name"); mypart=mypart.apply(); string prevname = mypart.getprperty("name"); RequestState.Add("prevName", prevname); //Add value t SessinState return this; OnAfterUpdate event string prevname = (string)requeststate["prevname"]; string curname = this.getprperty("name"); if (prevname!= curname) { //D sme lgic here //Perfrm cleanup f RequestState RequestState.Remve("prevName"); //remves single key // t remve all keys use RequestState.Clear(); return this; 7.32 Hw t reference custm DLL frm server methd Yu want t reference a custm library frm inside an Aras Innvatr Server Methd Technique Create a custm DLL that references the IOM. This DLL is then added t the BIN flder and referenced in the methd-cnfig.xml, allwing it t be called frm a server side methd Aras Crpratin All Cpyrights Reserved. 77

78 Create the custm DLL T create the custm DLL, it is necessary t create a Visual Studi C# class library prject using.net 4. The prject needs t reference the IOM f the versin f Aras Innvatr yu are cnnecting t. Class Cde namespace CkBkCustmDLL { public class CustmDLLFunct { public static string returnuser(innvatr inn) { string userid = inn.getuserid(); return userid; Cde tree setup with new DLL Once yu have created the DLL and built the assembly, yu need t use the steps belw t add the DLL t yur Aras Innvatr cde tree 1. Cpy the CkBkCustmDLL.dll and CkBkCustmDLL.pdb int the \Innvatr\Server\bin flder 2. Open fr Edit the \Innvatr\Server\Methd-Cnfig.xml and add the highlighted line... <ReferencedAssemblies> <name>system.dll</name> <name>system.xml.dll</name> <name>system.web.dll</name> <name>system.data.dll</name> <name>system.cre.dll</name> <name>system.cnfiguratin.dll</name> <name>$(binpath)/iom.dll</name> <name>$(binpath)/innvatrcre.dll</name> <name>$(binpath)/crecs.dll</name> <name>$(binpath)/spcnnectr.dll</name> <name>$(binpath)/cnversinmanager.dll</name> <name>$(binpath)/ckbkcustmdll.dll</name> Search fr the <Template> tag fr the language yu are using and include the additinal namespace yu need by adding additinal "using" lines. a. When adding lines, ensure yu update the line_number_ffset fr accurate debugging messages. <Template name="csharp" line_number_ffset="41"> <![CDATA[ using System; using CkBkCustmDLL; 4. Save the Methd-Cnfig.xml 2015 Aras Crpratin All Cpyrights Reserved. 78

79 Call new DLL frm Innvatr Server methd. Cde snippet that can be used as a reference fr hw t call yur assembly and functin Cde Snippet Innvatr inn = this.getinnvatr(); string userid = CustmDLLFunct.returnUser(inn); Assembly Redirectin If yur custm DLL references the current versin f the IOM, and yu upgrade Aras Innvatr t a newer versin, yur functin fills t execute due t an assembly mismatch n the IOM. A quick wrkarund until the DLL can be rebuilt referencing the latest IOM is t add an assembly redirect. T add an assembly redirect, yu need t add the fllwing int the <cnfiguratin> sectin f the \Innvatr\Server\web.cnfig file. <runtime> <assemblybinding xmlns="urn:schemas-micrsft-cm:asm.v1"> <dependentassembly> <assemblyidentity name="iom" publickeytken="524d880b " culture="neutral" /> <bindingredirect ldversin=" " newversin=" " /> </dependentassembly> </assemblybinding> </runtime> The ldversin, highlighted in yellw abve, is the riginal versin f the IOM.dll referenced by the custm DLL. The newversin, highlighted in red text abve, is the versin f the IOM.dll that is lcated in the upgraded instance f Aras Innvatr Hw t add sub menus t cntext menu in search grid There is a pssibility f adding sub menus t the cntext menu in the search grid f Aras Innvatr menu items. Aras.Client.Cntrls.CntextMenu cntrl supprts submenus. It prvides tw methds fr adding menu items: 1. add(id, label, parentmenuid, args); 2. addrange(items, parentmenuid); Belw are the examples given fr itemsgrid.html: Example #1 var menu = grid.getmenu(); menu.add("item_0", "Item 0"); menu.add("item_0.0", "Item 0.0", "item_0", { nclick: functin () { alert(0); ); menu.add("item_0.1", "Item 0.1", "item_0", { nclick: functin () { alert(1); ); menu.add("item_0.2", "Item 0.2", "item_0", { nclick: functin () { alert(2); ); 2015 Aras Crpratin All Cpyrights Reserved. 79

80 Example #2 var menu = grid.getmenu(), submenus = [ { id: "item_0.0", name: "Item 0.0", nclick: functin () { alert(0);, { id: "item_0.1", name: "Item 0.1", nclick: functin () { alert(1);, { id: "item_0.2", name: "Item 0.2", nclick: functin () { alert(2); ]; menu.add("item_0", "Item 0"); menu.addrange(submenus, "item_0"); 2015 Aras Crpratin All Cpyrights Reserved. 80

81 8 Aras Innvatr Slutin Studi The Aras Innvatr Slutin Studi is the user interface yu use t authr the cde fr yur Innvatr Methds. It is autmatically launched when yu pen a Methd Item in Aras Innvatr client. 8.1 Features The Slutin Studi ffers several useful features t help aid yu in the develpment f yur Methds. A rbust text editr with search/replace and und/red capabilities. Clr cding the keywrds fr the language yu are develping in. An IOM API cde guide. An nline help interface that is cntext sensitive fr the methds selected in the cde guide. Syntax checking based n the language yu are develping in. Und/Red Syntax checker Search/Replace IOM API Cde Guide Keywrd Clr Cding IOM API Online Help Figure Aras Crpratin All Cpyrights Reserved. 81

82 9 Debugging Aras Innvatr has the fllwing features fr debugging/lgging yur Methds: Visual Studi t debug Methds either client r server. Lgging f debug messages t an XML frmatted lg file. 9.1 Enabling Debugging in Aras Innvatr Server methd debugging is disabled by default in Aras Innvatr This setting saves disk space as the temprary dlls used fr debugging the methds d nt need t be created. T enable the debugging f Server Methds, yu can add the fllwing line t yur InnvatrServerCnfig.xml, lcated in the rt flder f yur installatin. <perating_parameter key="debugservermethd" value="true" /> Server methd debugging can then be disabled again by changing the value f this line t false. After changing this value, yu shuld restart IIS t cnfirm the change is applied. 9.2 Setting up VS.NET 2012 t debug Server side Methds 1. Open "Micrsft Visual Studi.NET 2012" debugger. 2. Chse Tls --> Attach t Prcesses. Figure Aras Crpratin All Cpyrights Reserved. 82

83 3. Chse w3wp.exe and click 'Attach'. Figure Chse Debug --> Exceptins t frce the methd int the debugger when an exceptin ccurs and chse the check bxes "Thrwn". Figure Optinally, yu can include the line System.Diagnstics.Debugger.Break() t frce a breakpint at a specific line in yur methd Aras Crpratin All Cpyrights Reserved. 83

84 9.3 Setting up VS.NET 2012 t debug Client side Methds 1. Include the line debugger; t yur Methd. 2. Open "Internet Explrer" t set debugger ptins. 3. Chse Tls --> Internet Optins. Figure Select the Advanced tab and make sure the "Disable Script Debugging" is turned ff and "Display ntificatin abut script errrs" is turned n. Figure In Internet Explrer, key in yur Aras Innvatr URL (D nt lg in yet). 6. Open Visual Studi In the menu, select "Debug" and "Attach t Prcess". 8. Find the "iexpre.exe" prcess with the "Title" that matches yur Aras Innvatr instance Aras Crpratin All Cpyrights Reserved. 84

85 9. Select it and click "Attach". Figure Return t the lgin screen fr Aras Innvatr and press F5 t refresh the page. 11. Lg in t Aras Innvatr. 12. Run the Methd and the applicatin switches t the "Micrsft Visual Studi.NET 2012" debugger and break n the debugger; line. 9.4 Setting up the server side lgging Add the fllwing lines t the InnvatrServerCnfig61.xml file: <perating_parameter key="debug_lg_flag" value="true" /> <perating_parameter key="debug_lg_prefix" value="c:/temp/debug-" /> <perating_parameter key="debug_lg_limit" value="1000" /> In rder t write messages t the C:/TEMP/DEBUG-* lg file, add the fllwing lines f cde t the server side methd: Dim sc as Object = Me.serverCnnectin sc.cc.startup.debuglg("unique string t identify message in lg file", "Actual message written t lg file") 2015 Aras Crpratin All Cpyrights Reserved. 85