Aras Innvatr 11 Package Imprt Exprt Utilities Dcument #: 11.0.02015040601 Last Mdified: 1/4/2018
Aras Innvatr 11 Package Imprt Exprt Utilities Cpyright Infrmatin Cpyright 2018 Aras Crpratin. All Rights Reserved. Aras Crpratin 300 Brickstne Square Suite 700 Andver, MA 01810 Phne: 978-691-8900 Fax: 978-794-9826 E-mail: Supprt@aras.cm Website: http://www.aras.cm Ntice f Rights Cpyright 2018 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 http://www.pencntent.rg/penpub/). 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. 2018 Aras Crpratin All Cpyrights Reserved. 2
Aras Innvatr 11 Package Imprt Exprt Utilities Table f Cntents Send Us Yur Cmments... 4 Dcument Cnventins... 5 1 Overview... 6 2 Data Mdel... 7 3 Using Package Imprt Exprt Utilities... 8 3.1 AML Packages... 8 3.1.1 The File Structure... 8 3.1.2 The Manifest File... 8 3.2 Exprt Tl... 9 3.3 Imprt Tl... 11 3.4 Cnsle Upgrade Tl... 13 3.5 Package Definitin Tl... 14 3.5.1 The Package Definitin Tl GUI... 15 3.5.2 The Package Definitin Tl Cmmand Line... 15 3.6 Creating a Package Definitin frm the Aras Innvatr UI... 16 3.6.1 What t include in a Slutins AML Package... 17 2018 Aras Crpratin All Cpyrights Reserved. 3
Aras Innvatr 11 Package Imprt Exprt Utilities 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: Email: Supprt@aras.cm Subject: Aras Innvatr Dcumentatin Or, Or, Pstal service: Aras Crpratin 300 Brickstne Square Suite 700 Andver, MA 01810 Attentin: Aras Innvatr Dcumentatin FAX: 978-794-9826 Attn: Aras Innvatr Dcumentatin If yu wuld like a reply, prvide yur name, email address, address, and telephne number. If yu have usage issues with the sftware, visit http://www.aras.cm/supprt/ 2018 Aras Crpratin All Cpyrights Reserved. 4
Aras Innvatr 11 Package Imprt Exprt Utilities 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. 2018 Aras Crpratin All Cpyrights Reserved. 5
Aras Innvatr 11 Package Imprt Exprt Utilities 1 Overview The main implementatin methd fr a new functinality in Aras Innvatr is creatin f a set f items that encapsulate the desired functinality - sme items represent business bjects (ItemTypes and their instances), sme supprt user interactin (Frms, etc.), sme may implement business lgic (Methds), etc. Because all Aras Innvatr items are stred in the database it creates numerus prblems with identifying differences between different installatins f Aras Innvatr, keeping track f them, merging the differences, and upgrading t new releases. In rder t implement a better mechanism fr slving these prblems, Aras Crpratin has created a set f tls called Package Imprt Exprt Utilities, whse purpse is fr it imprt, exprt and management f AML packages. Outlined here are sme f the main ideas that this set f tls based n. First, the idea f representing each item in a frm f a separate AML files, which in its turn wuld allw: The use f a visual cmparisn between different versins f the same AML file. The use f third party visual merge tls fr merging differences between different versins f the same AML file. Keeping custm slutins r any set f related items including thse that implement cre Aras Innvatr functinality in XML frm in a file structure and keep track f their changes. Secnd, the idea f rganizing a set f lgically related items int a package. Tgether these cncepts allw simplifying the prcess f imprting and exprting Aras Innvatr cre, BRS s, and custm slutins t and frm the database. This allws administratrs t keep track f mdificatins, merge differences between packages, and migrate these changes between databases. The main gals fr Package Imprt Exprt Utilities set are: The ability t create and mdify AML packages in the database. The ability t exprt the sme r all f the cmpnents f an AML package frm a database t the file system in a frm f a hierarchal set f AML files. The ability t imprt a hierarchy f AML files that represent a package t a database. If the package already exists in the database, the imprt prcess must prvide an ability t autmatically merge the differences between items int the database frm crrespnding imprted AML. 2018 Aras Crpratin All Cpyrights Reserved. 6
Aras Innvatr 11 Package Imprt Exprt Utilities 2 Data Mdel Cnceptually each package is a cllectin f item IDs. There are a certain ItemTypes that were intrduces t supprt package functinality. The fllwing represents the cmmn set f items that defines an AML package: Nte: PackageElement The Package element represents ID number f the item that has been defined in the database. PackageGrup This represents the type f ItemType (Methd, List, etc.) that the Package Elements are added frm. This ItemType als defines the name f the flder the Package Element is exprted t in the file structure. PackageDefinitin This is the package itself. It represents the cllectin f package grups that makes up a package, and allw fr the gruping f ne package separate frm the next. PackageDependsOn This is a relatinship type that establish dependencies between packages PackageReferencedElement This is a relatinship n PackageDependsOn type that defines what exact package elements frm the related package the surce package references. This culd be useful when packages are exprted (check-bx Exprt Referenced Items in Exprt tl; see sectin Exprt Tl fr mre details). N Package Element may belng t mre than ne AML package. This is t prevent cnflicts when imprting the packages, if these tw elements are nt identical in each package. The imprt wuld have n way f knwing which AML was the crrect AML t apply therwise. A newly installed Aras Innvatr database cntains Package Definitins f tw types: Cre Packages These packages are used t define the basic structure f every innvatr database, regardless f what slutins are used in the database. Slutin Packages These packages define the elements that cmprise the definitin and functinal rules f different BRS s data mdels. 2018 Aras Crpratin All Cpyrights Reserved. 7
Aras Innvatr 11 Package Imprt Exprt Utilities 3 Using Package Imprt Exprt Utilities 3.1 AML Packages The first step in understanding the use f the Package Imprt Exprt Utilities is t understand the structure f package AML files n disk and the crrespnding manifest file. 3.1.1 The File Structure The flder structure f a cre package can be defined by careful use f the Package Definitin name. Let s use the cre Dashbard package as an example. Nte that fully qualified package name f this Package Definitins is cm.aras.innvatr.dashbard. When exprted, this package is exprted t a hierarchal structure as such: Innvatr/ Imprts/ Cm/ Aras/ Innvatr/ Dashbard/ Any new packages are treated as such, and allw fr the exprt f packages in this manner. Nn-cre packages d nt use this same rule fr exprt despite the fact that slutin package have a fully qualified names. I.e. this name is nt translated int a directry hierarchy f cm\aras\... Instead, the three slutin packages always exprt t the predefined flders: Slutins/ PLM/ Imprt/ Prject/ QP/ Imprt/ Imprt/ 3.1.2 The Manifest File The manifest file cntains infrmatin abut what packages can be prcessed by the utilities, dependencies between packages and where t find package s AML files. Here is an example f a manifest file: <imprts> <package name="cm.aras.innvatr.slutin.plm" path="plm\imprt" /> <package name="cm.aras.innvatr.slutin.qp" path="qp\imprt > <dependsn name="cm.aras.innvatr.slutin.plm" /> </package> <package name="cm.aras.innvatr.slutin.prject" path="prject\imprt"> <dependsn name="cm.aras.innvatr.slutin.plm" /> </package> 2018 Aras Crpratin All Cpyrights Reserved. 8
Aras Innvatr 11 Package Imprt Exprt Utilities </imprts> package tag Attribute name f package unique fully qualified name f the package Attribute path f package path t the directry that cntains the package AML files. Nte: Path t the package s AML files culd be either abslute r relative; in case f relative path, it s relative t the lcatin f the manifest file itself. Fr all nn-cre packages, this path is the path t the directry where the flders fr the different AML types are stred. Frm ur example in the previus sectin The File Structure, if the manifest file fr the cm.aras.innvatr.slutins.plm package is placed in the Slutins flder then the path t the PLM slutin AML pints t the \PLM\Imprt flder where the \ItemType, \Frm, etc. flders are (path relative t the lcatin f the manifest file itself is used), and the package tag wuld be written s: <imprts> <package name="cm.aras.innvatr.slutin.plm" path="plm\imprt" /> </imprts> Fr cre packages (admin, cre, dashbards, and preferences), the path t package AML files is calculated based n the specific package name. Fr cre packages the. in the fully qualified name f a cre package is replaced with a \ when calculating the file path based n these specific package names. Frm ur example in the previus sectin The File Structure, if the manifest file fr the cm.aras.innvatr.dashbards package is placed in the \Innvatr\Imprts flder, then the package tag wuld be written s: <imprts> <package name="cm.aras.innvatr.dashbards" path=".\" /> </imprts> depenedsn tag This tag cntains the infrmatin abut packages that the package defined in the package tag depends n. This als ppulates the Package Depends On relatinship f the Package Definitin item in the database. This infrmatin is used fr creating in the database dependencies between packages. If the package referenced in the dependsn tag is ne f packages imprted in the imprt sessin, then it is laded prir t the package that depends n it; therwise it s assumed that the package referenced by the dependsn tag already exists in the target database Nte: If it desn t then the imprt might fail because imprted package might cntain references t sme items frm the dependsn package. 3.2 Exprt Tl The Exprt tl allws user t select Package Elements t exprt t the file system as XML. These package elements can be exprted individually, as part f a Package Grup, r as part f a Package Definitin. 2018 Aras Crpratin All Cpyrights Reserved. 9
Aras Innvatr 11 Package Imprt Exprt Utilities Figure 1. 1. The first step in using this utility is cnnecting t the Innvatr Server. T d this, we must first define the fields fr ding s: Server: The URL used t lgin t Innvatr. A default install uses a URL such as http://lcalhst/innvatrserver Database: The database yu wish t exprt the package frm. This filed is ppulated by selecting the ellipse t the right f it, after filling ut the Server URL field. Username: The lgin f the user that is used lg int Aras Innvatr. This is usually the rt r admin lgins when wrking in a nn-prductin r upgrade envirnment. Passwrd: This is the passwrd fr the lgin filled ut in the Username field. After all f this infrmatin is filled ut, select the Lgin buttn t cnnect t the Innvatr Server. 2. The secnd step in running the utility is the Exprt Optins. Exprt T: The lcatin in the file system where yu wish t exprt the AML packages t. Levels: This field is used t specify the levels attribute f the query in a limited number f ItemType queries nt pre-defined by the tl. Exprt Referenced Items: This ptin is used t exprt Items explicitly defined in the package definitin as a referenced Item. 2018 Aras Crpratin All Cpyrights Reserved. 10
Aras Innvatr 11 Package Imprt Exprt Utilities References t Unknwn Packages: by Unknwn Package it s meant here a package that is neither a cre package nr a package that the exprted package depends n ( depends n means that there is a dependency f type PackageDependsOn between exprted package and the ther package). If an item has references t items in the unknwn package, these references are nrmally remved during the exprt. One example f this is the Quality Planning Identity. The Quality Planning Identity is used in the New Part Permissin, and because the Quality Planning slutin depends n the Prduct Engineering slutins exprting this relatinship culd create a circular reference. Therefre, the reference must be handled. Remve Silently: References t unknwn packages are remved. (The New Part Permissin cntains n reference t the Quality Planning, and this remval is nt lgged.) Remve with Warning: References t unknwn packages are remved, and a warning is given t allw the user t reslve this reference separately. (The New Part Permissin cntains n reference t the Quality Planning.) Dn t Remve: References t unknwn packages are nt remved (The New Part Permissin cntains reference t the Quality Planning. This can cause imprt errrs if the Quality Planning Identity des nt exist in the database when the created package is imprted.) 3. The last step is t chse what Package Elements shuld be exprted in the Available fr Exprt sectin. Use the ellipse next t the left panel t refresh the list f available elements fr exprt. It is pssible t exprt nly a part f a package by expanding the package in the list f packages n the bttm left f the frm and selecting a particular package grups in the tree and/r particular items in the list f items n the bttm right f the frm fr exprt. 3.3 Imprt Tl The Imprt tl allws user t select predefined manifest files, and imprt the crrespnding package AMLs int a database. 2018 Aras Crpratin All Cpyrights Reserved. 11
Aras Innvatr 11 Package Imprt Exprt Utilities Figure 2. 1. The first step in using this utility is cnnecting t the Innvatr Server. T d this, we must first define the fields fr ding s: Server: The URL used t lgin t Innvatr. A default install uses a URL such as http://lcalhst/innvatrserver Database: The database yu wish t imprt the package t. This filed is ppulated by selecting the ellipse t the right f it, after filling ut the Server URL field. Username: The lgin f the user that is used lg int Aras Innvatr, and apply the package AML. This is usually the rt r admin lgins when wrking in a nn-prductin r upgrade envirnment. Passwrd: This is the passwrd fr the lgin filled ut in the Username field. After all f this infrmatin is filled ut, select the Lgin buttn t cnnect t the Innvatr Server. 2. The secnd step in running the utility is the Release Settings. This defines the target database release versin number f the package being imprted and the descriptin f the purpse f the imprt. Release Settings are als used by Aras Innvatr classes that allw user t btain infrmatin abut database upgrades applied t the database. Target Release: The target release number f the database after the imprt is cmplete. When migrating packages, this is the current versin number f the database (11.0 t 11.0 imprts). When upgrading a database, this is the upgrade target versin f the database (9.4.0 t 11.0 imprts). Descriptin: A brief descriptin f the imprts purpse. 2018 Aras Crpratin All Cpyrights Reserved. 12
Aras Innvatr 11 Package Imprt Exprt Utilities 3. Next, the user must specify a manifest file that cntains infrmatin abut what packages and frm where n disk shuld be imprted int the database. 4. Furth, the user must select what packages frm the manifest t imprt t the database frm the Available fr Imprt sectin. 5. Last, a chice must be made as t hw cnflicts with existing packages in the database shuld be reslved. The main display f this sectin shws what packages are already present in the database. Type: Determines hw existing element in a package is handled. Ignre - Skip imprted items if they already exist in the database Merge - Update package items in the database with the new AML If item actin specified in AML is nt add it always used as is If item actin specified in AML is add then it s replaced by edit if item with the ID already exists in the database. Mde: Determines the level f errr checking that is perfrmed befre an AML is imprted t the database. Fast - N additinal verificatins f the imprted AML is dne during the imprt prcess. Thrugh - During the imprt additinal checks abut the AML s dependent items are checked fr existence in the database befre applying. (e.g. making sure all prperties exist with the crrect ID befre attempting t apply an ItemType) Aras recmmends that imprted AML files always cntain item actin add fr every imprted item unless it is specifically required therwise (e.g. the item with a particular ID must be remved frm the database). Anther imprtant thing t understand is hw the imprt prcesses versined items. Package Elements always cntains a cnfig_id f a versinable item. When a versinable item is imprted its first made an attempt t find its cnfig_id and then use the ID in the Package Element. Crrespndingly, exprting a versinable item always writes its cnfig_id as id in the resulting AML file (see Exprt abve). 3.4 Cnsle Upgrade Tl The Cnsle Upgrade Tl is a cmmand line versin f bth the Exprt Tl and Imprt Tl described abve. The cmmand line parameters can be btained by typing /? as the cmmand line parameter. Required Parameters : server=url server's URL (e.g. server=http://lcalhst/innvatrserver) database=db database's name (e.g. database=dbwithutslutin) lgin=uname user's lgin (e.g. lgin=rt) NOTE: lgin must have rt r admin privileges passwrd=pw user's passwrd (e.g. passwrd=xxxx ) release=rel release's name used by imprt nly (e.g. release=rel11.0) mffile=path explicit path t.mf file (Nt required fr exprt. Default behavir is exprt all ) Optinal Parameters : imprt merge imprt r exprt (by default exprt) used by imprt nly (by default uses nn-merge ptin) 2018 Aras Crpratin All Cpyrights Reserved. 13
Aras Innvatr 11 Package Imprt Exprt Utilities fastmde verbse used by imprt nly (by default uses thrugh mde that prvides mre thrugh verificatin f the applied AML) used by imprt and exprt (by default uses nn-verbse) dir=d1 exprt: utput directry imprt: lcatin f the manifest file NOTE: the specified path must exist. If the parameter is nt specified at all, user is prmpted fr the path lg=lgpath full path t the lg file. If specified file already exists it's appended. descriptin=desc release descriptin used by imprt nly (e.g descriptin="slutinsupgrade") vlg save the resulting lg file n the vault (dn't save if the argument wasn't specified) level=n request attribute 'level' that is used fr nn-dictinary item types (used by exprt nly) default: level=1 3.5 Package Definitin Tl The Package Definitin Tl allws creating an instance f the Package Definitin in the database. This is a temprary utility that is created nly fr the situatins when Aras Innvatr has a set f items that makes up a Package Definitin, but these items are nt included as part f a Package Definitin. Generally, this nly ccurs when the database was upgraded frm a versin f Aras Innvatr that predated the crrespnding use f Package Definitins fr this slutin. Nte: The Package Definitin Tl des NOT imprt anything int the database. It creates a Package Definitin in the database that later can be used fr managing the Package Elements. 2018 Aras Crpratin All Cpyrights Reserved. 14
Aras Innvatr 11 Package Imprt Exprt Utilities 3.5.1 The Package Definitin Tl GUI Figure 3. 1. The first step in using this utility is specifying a manifest file that cntains infrmatin abut what packages and frm where n disk shuld be defined in the database. 2. The next step is t establish the cnnectin parameters: Server: The URL used t lgin t Innvatr. A default install uses a URL like http://lcalhst/innvatrserver Database: The database yu wish t define the package in. This filed is ppulated by selecting the Get DB List buttn, after filling ut the Server URL field. Username: The lgin f the user that is used t lg int Aras Innvatr. This is usually the rt r admin lgins when wrking in a nn-prductin r upgrade envirnment. Passwrd: This is the passwrd fr the lgin filled ut in the Username field. After all f this infrmatin is filled ut, click Create Package Definitin t begin. 3.5.2 The Package Definitin Tl Cmmand Line Alternately, the Package definitin tl can be executed frm the cmmand line. The cmmand line parameters can be btained by typing /? as the cmmand line parameter. Usage: PackageDefinitin.exe {server url} {user} {passwrd} {db} {path t manifest file} server url server's URL (e.g. http://lcalhst/innvatrserver) user user's lgin 2018 Aras Crpratin All Cpyrights Reserved. 15
Aras Innvatr 11 Package Imprt Exprt Utilities passwrd database path t manifest file NOTE: lgin must have rt r admin privileges user's passwrd database's name lcatin f the manifest file NOTE: the specified path must exist EXAMPLE: C:\PackageImprtExprtUtility\PackageDefinitin\PackageDefinitin.exe http://lcalhst/innvatrserver rt innvatr InnvatrSlutins C:\Slutins\cre_imprts.mf 3.6 Creating a Package Definitin frm the Aras Innvatr UI Package Definitins can als be created fr new slutins using administratr features in the Aras Innvatr user interface. These packages shuld be created with a specific data mdel in mind, and yu shuld be careful t review yur package fr any referenced items that may nt be in the next database yu imprt t. Lists, fr instance, are cmmnly frgtten when creating a package definitin, but causes errrs when trying t imprt ItemTypes that reference them. In rder t create a package definitin, yu must be an administratr in Aras Innvatr. 1. Frm the main search grid highlight the Item yu wish t add t a package. 2. Frm the main menu, select Tls--> Admin --> Add t Package. Figure 4. 3. Frm the dialg, ether select an existing package r create new If yu select an existing package, the item is added t the existing package, and yu are dne. 4. If yu select create new yu are prmpted t define the new package. 2018 Aras Crpratin All Cpyrights Reserved. 16
Aras Innvatr 11 Package Imprt Exprt Utilities Figure 5. Package name shuld be alphanumeric withut spaces, as a best practice. The package name is used t create file flder names n exprt. Dependency shuld be the packages that are required t exist in the database befre the defined package can be imprted. After yu have created yur package, yu may review it and ther existing package definitins by selecting Administratin\Package Definitins in the TOC. 3.6.1 What t include in a Slutins AML Package There is n fixed list fr what Items t include in a slutins AML package, because the list wuld change based n the versin f Aras Innvatr r slutin yu are wrking with. Hwever, there is a basic list f the Cre ItemTypes that make up the basic metadata f a database. This is NOT a definitive list, but shuld act as a helpful guideline when creating yur packages. Actins CmmandBarSectins E-Mail Messages Frms Grids Identities ItemTypes (Exclude ItemTypes with is_relatinship=1) Life Cycle Maps Lists (Exclude Lists assciated with PlySurces like Change Cntrlled Item and Deliverable ) Methds Permissins PresentatinCnfiguratins 2018 Aras Crpratin All Cpyrights Reserved. 17
Aras Innvatr 11 Package Imprt Exprt Utilities RelatinshipTypes Reprts Sequences SQLs Wrkflw Maps 2018 Aras Crpratin All Cpyrights Reserved. 18