CHAPTER 4 one nue Project Setup Excel Import and Export is designed to make the process of setting-up an AVEVA Plant project easier by allowing Administration data to be imported via spreadsheets. Itis important that the Excel Spreadsheets used for both the Import and Export functions are in the correct format. The required format is the same for both functions, therefore the correct format can easily be obtained by exporting data from the Administration module and examining the results. 4.1 Export to Excel The Export to Excel utility can be accessed by selecting Utilities > Export from the main menu of the Administration module. The Admin Export form will be displayed. From this form the User can enter a file path for the export fie. Alternatively the (=) icon can be used to navigate to a ema) suitable fle location. = = oma cee a= On clicking the OK button of the Admin Export form the Export process is started, ‘An export summary screen is displayed. Task progress is displayed in this form. In the event of an error occurring during the export process, it will be noted in this form © Copyright 1974 to current year. 45 AVEVA Solutions Limited and its subsidiaries. ‘Al rights reserved,AVEVA Plant (12.1) ‘System Administration (Advanced) TM-1301 4.2 Admin Excel Spreadsheet ‘The Admin Excel Spreadsheet has a specific format containing a | A,” keyword and the appropriate headings. 3 tar ore The spreadsheet is split down into various tabs.This training “Yass course will focus on the Extracts and Data Access Control tabs. am sen estton 4.2.1_Admin Excel Spreadsheet — Extract Databases ‘The required format for Extract Databases is shown below. Data in some columns can be altered without restriction (e.g. Description), while other columns reflect a value within an appropriate context (e.g. Claim Mode can only be Implicit or Explicit). Guidance on the values required in each column are provided below. Pe & J I 1 Keyword Owning Team Name Description Parent. ‘Claim Mode Variant 2 EXTRACT BXTEAMC — DESI_X2 IMASTERA/DESI IMPLICIT No 5 EXTRACT EXTEAME DESI XL IMASTERA/DESI IMPLICIT Ne ‘Keyword EXTRACT. Owning Team Name of the Team that owns the Extract Database. Name Extract Name (part after /). Description Description of Database. Parent Parent Database. Claim Mode IMPLICIT or EXPLICIT. Variant Yes or No. ‘© Copyright 1974 to current year. AVEVA Solutions Limited and its subsidiaries. All rights reserved, 46AVEVA Plant (12.1) ‘System Administration (Advanced) TM-1301 4.2.2 Admin Excel Spreadsheet - Working Extract Databases ‘The required format for Working Extract Databases is shown below. Data in some columns can be altered without restriction (e.g. Description), while other columns reflect a value within an appropriate context (e.g. Claim Mode can only be Implicit or Explicit). Guidance on the values required in each column are provided below. T é T. 1 emord—_Ouming User Description Parent Claim Mode Variant 2 WORKEKTRACT USERA EXTRACT OF MASTERA/DESI MASTERA/DESI IMPLICIT No. 5 WORKEXTRACT USER EXTRACT OF MASTERA/DESI MASTER/DESI IMPLICIT No 4 WORKERTRACT USERC __EXTRACTOF MASTERA/DESI_MASTERA/OESI IMPUCIT No ‘#Keyword WORKEXTRACT. (Owning User Name of the User associated with the Working Extract Database. Description Description of Database. Parent Parent Database. Claim Mode IMPLICIT or EXPLICIT. Variant ‘Yes or No. 4.2.3 Admin Excel Spreadsheet - Scope On export, Data Access Control requirements are separated into their component parts, ACR.s, ACR Groups, Scopes, Roles and Perops. The required format for Scopes is shown below. As with the other spreadsheets considered, data in some columns can be altered without restriction (e.g. Description), while other columns reflect a value within an appropriate context (e.g. Selection could utilise the keyword ALL). Guidance on the values required in each column are provided below. ‘Keyword SCOPE Name Name of Scope. Description Description of Scope. Selection ALL (keyword). Alternatively, Sites or Zones specific to the project could be used. © Copyright 1974 to current year. a7 AVEVA Solutions Limited and its subsidiaries. All rights reserved,AVEVA Plant (12.1) ‘System Administration (Advanced) TM-1301 4.2.4 Admin Excel Spreadsheet — Roles and Perops Roles are specified followed by the associated Permissible Operation (PEROP). Roles require only three fields. Guidance on the values required to define the Role are given below. [ALLDESIONER Can geateAL PONS ements PPING DESIGNER Pig Designer PING DESIGNER PE-DESIONER PE Pe (2r7m PUR OF Zone Ea BBE AND ATTRIFUNC NEG SSLED') Pie bescneR aL (arma FUNCOF PPE NEQISSLKD) ‘#Keyword ROLE. Name Name of the ROLE. Description Description of ROLE. Permissable Operations require considerably more fields to account for all Create, Modify and Delete ‘operations and any associated error messages. Guidance on suitable values is provided below. 1 You emt reste eros Elmont 2 Yovean only create pipes ina Ppngzone thas notbeen sued ‘#Keyword PEROP. Owner Owning Role. Name Name of Perop. © Copyright 1974 to current year. 48 AVEVA Solutions Limited and its subsidiaries, All rights reserved.AVEVA Plant (12.1) ‘System Administration (Advanced) TM-1301 Element types Element Type e.g. PIPE, EQUIPMENT HIERAR, ALL etc. Qualifying condition Qualifying Rule. Often this will utilise a Purpose or Function of a model element OpCreate GRANT or DENY ability to Create Elements. OpModity GRANT or DENY ability to Modify Elements, OpDelete GRANT or DENY ability to Delete Elements. Opciaim GRANT or DENY ability to Claim Elements. Opissue GRANT or DENY ability to Issue Elements. OpDrop GRANT or DENY ability to Drop Elements, Opoutput GRANT or DENY ability to Output Elements. OpExport GRANT or DENY ability to Export Elements. OpCopy GRANT or DENY ability to Copy Elements. Attributes Specify attributes that can be changed or ALL. Error message Error Message displayed to the User. 4.2.5 Admin Excel Spreadsheet - ACR The required format for an ACR is shown below. As with the other spreadsheets considered, data in some columns can be altered without restriction (e.g. Description), while other columns refiect a value within an appropriate context (e.g. Scope will reference a valid Scope in the project). Guidance on the values required in each column are provided below. || skeyword Name Description scope Role 2 ACR ALLDESIGN Can create AL items anywhere ALLSCOPE ALL-DESIGNER 3 ACR ALLPIPES all pipes [ALLSCOPE PIPING-DESIGNER AcRs RER Group Keyword ACR. Name Name of ACR. Description Description of ACR. Scope Name of the Scope. Role Name of Role. 4.3 _Import from Excel TE The Import from Excel utility can be accessed by SS selecting Utilities > Import from the main menu of A) Adimin Display Query Setings | Unites [Project Help Ca — the Administration module. ee ‘The Admin Impert form will be displayed. From this = form the User can specify a file path forthe file to be — imported. Alternatively the LJ icon can be used to imeem Ty | navigate to a suitable file location. PBSSS mee @ ere attempting en Excel Inport make sure oy TEAMUVASTER. Hic sas that the Access Control Assistant is not dhploye 3 opigh 17410 caret yoar we AVEVA Solutions Limited and its subsidiaries. All rights reserved,AVEVA Plant (12.1) ‘System Administration (Advanced) TM-1301 Once the file has been specified, clicking the OK button on the Admin Import form instigates the Import operation. If the project references a Foreign Project the User will be prompted to give suitable login credentials for an a Free User in the referenced project. ‘An import summary screen is displayed. Task progress is displayed in this form. In the event of an error occurring during the export process, it will be ‘noted in this form. @® if errors are present it is possible to role back the System database until a point before the import operation was instigated. 4.3.1 Selecting an MDB for User Defined Data ‘Once the import operation has finished, the System Administrator is prompted to supply an MDB if one has ana a If the imported data contains UDA's or UDET's then the MDB selected should contain a Lexicon Database. As DAC may contain references to UDA's or UDET’s it is important that this is checked prior to importing the data, If DAC has not been specified, and neither UDA's or UDET's have been used, the System Administrator can select . = Minors ‘© Copyright 1974 to current year. 50 AVEVA Solutions Limited and its subsidiaries, All rights reserved.4.4 Admin Database Rollback AVEVA Plant (12.1) ‘System Administration (Advanced) TM-1301 ‘The Admin Database can be rolled back following an Excel import in the event that errors were encountered. The Rollback utility can be accessed by selecting Utilities > Rollback from the main menu. The Rollback form is displayed showing the items that will be deleted, Selecting the Rollback button in the middle of the form instigates the process. Due to the nature of this process, ‘confirmation is immediately sought from the User. Ce5jee) Selecting the Yes button continues the process, while selecting the No button stops the process. If the Rollback process is continued, the lower portion of the Rollback form will be populated with tasks that have taken place. The user can verify the results of the Rollback process by refreshing the view of the Admin Explorer. ‘© Copyright 1974 to current year. AVEVA Solutions Limited and its subsidiaries, All rights reserved. 51AVEVA Plant (12.1) ‘System Administration (Advanced) TM-1301 Bannerer at ee ad Use the Export to Excel utility on the Training Project. Open the spreadsheet produced and create some new Teams, Users and Databases. Import the modified spreadsheet into the Training project, checking for any errors. Use the database Rollback function to restore the project to the point immediately before the Export utility was used. ‘© Copyright 1974 to current year. 52 AVEVA Solutions Limited and its subsidiaries, All rights reserved.CHAPTER 5 eee This chapter describes how to create and use PDMS PML Encryption or Published PML. Various levels of encryption can be applied to any PML functions, forms, abjects, and macros. 5.1_ Overview of PML Encryption PML is the AVEVA Programmable Macro Language. The details of the language may be found in the PDMS Software Customisation Guide and the POMS Software Customisation Reference Manual, supplied with the product PML functions, objects, forms and macros may be encrypted using the tools described in this chapter. Once encrypted they may be used within POMS but cannot easily be read. Please note that the encryption used is of limited strength, and is not secure against all possible attacks. Details of the encryptions used are described later. ‘Once a PML file has been encrypted, it is no longer possible to read or edit the file. The Published PML toolkit does not include a tool for un-encrypting files. It is good practise to ensure that a safe copy of the original file is retained, in case further modifications are required later. 5.2__ PML Encryption Utility Program ‘The encryption ulility program is a command window program designed to be included in the PML software development process. 5.2.1 Typical workflow When undertaking PML encryption tasks the following workflow should be adhered to: © Ensure that a current backup of the source PML is available. ‘© Copy the source folders to a new location. * Encrypt from the source location to the new location. ‘= Check the encryption is successful and the files work in the expected manner. © Not al fies within @ PML folder hierarchy are always PML. Images, for example, should not be encrypted, but may need tobe supplied wth the encrypted versions ofthe PML @® Automating the encryption procedure via batch files, perl script, or a PML script will make it easier to create the encrypted PML files when the source PML is updated. 5.2.2__Licensing The pmlencrypt.exe utility program requires a PML Publisher licence in the license file (the feature name is VPD-PMLPUBLISHER). If this is not present in the license then the program will not run. © Copyright 1974 to current year. 53 AVEVA Solutions Limited and its subsidiaries. ‘Al rights reserved,AVEVA Plant (12.1) ‘System Administration (Advanced) TM-1301 5.3__Using the PML Encryption Utility Program The form of the PML Encryption Utility Program can be seen by running pmlencrypt.exe without arguments (or with an inval jeten ae ret chaste “eivial =biFfor older beh Oe folders from pat torpath ‘e:\AUEURVPLamt The command is lid set of arguments). An output similar to that below is produced, zee 4B-his RCA oncsype ion fran, che ‘a pinple low tecurity encryption sigor ity sy 4 funtntacelshenalie encrageion echSne * for testing only ne encryption, but can be qsed vith “buffer M Chases" the Fie to Se"etained Un 'nonary Snell a nadue evitch E'tced to encrypt ALL files fron’ the Folder fronpath to top is used to encrypt ALL .pniohj -pnltne and .pnifen Files fron in a PHLLIE-tupe folder etructure beneath fron_path to to_path 4th iz the File or folder go be encrypted 45 the output filo or elder \Trainingl2 tN Teaining\tertencrypt? pense is of the form: pmlencrypt [-re4}-basic|-trivial|-none] [-buffer N] [-folder|-pmllib] from_path to_path Where: 04 -buffer N folder -pmillib from_path to_path uses 40-bit RC4 encryption from the Microsoft Base Cryptographic Provider (default). uses a simple low-security encryption algorithm, uses a human-decipherable encryption scheme - for testing only. no encryption, but can be used with -buffer N. ‘causes the file to be retained in memory until a module switch once it has been read N times (the default is never) is used to encrypt ALL files from the folder from_path to to_path. is used to encrypt ALL .pmlobj .pmitnc .pmifrm and .pmimac files from the folders in a PMLLIB-type folder structure beneath from_path to to_path. is the file or folder to be encrypted. is the output file or folder. ‘© Copyright 1974 AVEVA Solutions ‘to current year. 54 Limited and its subsidiaries, Al rights reserved.AVEVA Plant (12.1) ‘System Administration (Advanced) TM-1301 5.4 Choosing Files PML files are not required to have particular file extensions. PML2 functions, objects, forms and macros are normally stored in files with the extensions .pmifne, .pmlobj, .pmifrm and .pmimac respectively. However, other PML files such as those in the pdmsui folder of a PDMS installation do not have a file extension. ‘As any PML file (with or without a fle extension) may be read with a $m command, care must be taken when choosing files to encrypt. Other files, such as icon images and configuration files cannot be used by POMS ‘when enerypted 5.4.1_ Single File If neither of the ~folder or ~pmillib options are used the from_path and to_path arguments are taken to be single file-names or paths (which should not include embedded spaces). The to_path file is created or overwritten, as appropriate. This option may be used whenever there is a single file to encrypt, and can also be useful within a script, ‘where the file selection is handled by the script itself. No assumptions are made about file extensions, 5.4.2 All Files in a Folder If the -folder option is used the from_path and to_path arguments are taken to be names or paths of folders (which should not include embedded spaces). All files in the from_path folder are encrypted into the to_path folder. The to_path folder is created, if required, and the files inside it are overwritten, No file extension is required, so care must be taken not to encrypt non-PML files. 5.4.3 Files ina pmilib -like Folder Tree If the ~pmllib option is used the from_path and to_path arguments are taken to be names or paths of folders (which should not include embedded spaces). All folders beneath the from_path folder are scanned, and files with extensions .pmifne, .pmlobj, .pmifrm or .pmimac are encrypted to a matching structure constructed or overwritten beneath the to_path folder. As this option is file-extension sensitive, it will not encrypt, or copy, image or other unrelated files in the hierarchy. 5.4.4 File/Folder paths Care must be taken when the from_path and to_path arguments are given. The from path must precede the to_path, otherwise the wrong file may be overwritten. The from_path and to_path arguments cannot be identical. This is to reduce the risk of accidental ‘overwriting of the source-files. Embedded spaces are not supported in the paths. 5.5 Encryption Algorithms There are four encryption options that use different encryption algorithms. The following sections describe the four options. 5.5.1_Encryption Type 0: No Encryption Encryption Type 0 (No Encryption) adds a standard Published PML header to the file, ie. --<000>— Published PML 12.0 >--, but does not otherwise encrypt the file. It can be selected by choosing the -none option in the encryption call ‘© Copyright 1974 to current year. 55 AVEVA Solutions Limited and its subsidiaries. Al rights reserved.AVEVA Plant (12.1) ‘System Administration (Advanced) TM-1301 5.5.2 Encryption Type 1: Trivial Encrypt Encryption Type 1 (Trivial Encryption) is designed for testing purposes only. It provides no security, as the lines can be read backwards. It is used to establish that the encryption system is functioning correctly and that an incompatible version of POMS has not been installed. It can be selected by choosing the - vial option in the encryption call 5.5.3 Encryption Type 2: Basic Encryption Encryption Type 2 (Basic Encryption) is an alternative simple encryption algorithm which is implemented directly and does not rely on external libraries. It can be selected by choosing the -basic option in the encryption call. 5.5.4 Encryption Type 3: RC4 Encryption Encryption Type 3 (RC4 Encryption) is the recommended and default option. This encryption uses the Microsoft Base Cryptographic Provider, which is included in Windows 2000, Windows XP, and Windows 7 operating systems as well as Microsoft® Internet Explorer version 3.0 or later. Itis anticipated that all POMS compatible computers will include the libraries required for this algorithm. 40-bit keys are used to operate within limits imposed by (historic) limitations of encryption technology. It can be selected by choosing the -re4 option in the encryption call © Athough his is the most robust encryption algorithm provided, its stil of limited strength and is not Secure against all possible attacks 5.6 Encrypting PML Files ~ A Worked Example In this worked example supplied PML files will be encrypted using various options. 5.6.1 Supplied Files The pmlencrypt.exe by default is installed in the C:\AVEVA\Plant\Manage\PMLPublishert.1 folder. The following are the simple PML files that will be used for the encryption. The Trainer will provide these files by copying them from the Training Setup. Typically C:\AVEVA\Plant\Training12.1.1\Training\testencrypt. The files are as follows: C:\testencryptipmilib_original\forms\hello.pmifrm setup form !Ihello Tille ‘My Form Title’ Paragraph Message text ‘Hello world button .bye ‘Goodbye’ OK exit C:Mtestencryptipmilib-original\functions\area.pmifne define function Hlarea(/Radius is REAL) is REAL 'CircleArea = !Radius.Power(2) * 3.142 return !CircleArea endfunction ‘© Copyright 1974 to current year. 56 AVEVA Solutions Limited and its subsidiaries. Al rights reserved.AVEVA Plant (12.1) ‘System Administration (Advanced) TM-1301 C:Mtestencryptipmilib-originallobjects\life.pmlobj define object LIFE member Answer is REAL endobject define method Life() This. Answer = 42 endmethod define method .Answer() is REAL return !This.Answer endmethod define method -Answer(!Value is REAL) Ithis. Answer = IValue endmethod C:Mtestencryptipmillib-original\macros\newsite.pmimac new site ENCRYPT-SITE hhandio(41,12) $p site /ENCRYPT-SITE exits DELETE SITE return endhandle C:Mtestencryptipmilib_originallmacros\NZONE JENCRYPT-SITE handle(2,109) $p Site /ENCRYPT-SITE does not exist return endhandle new zone /ENCRYPT-ZONE handlo(41,12) $p site /ENCRYPT-ZONE exits, DELETE ZONE return endhandle 5.6.2 Directory Structure The PML files should be stored in the correct PML directory structure. a omar pear tom | [mein | [mee | [mee ed belgian Original file folders Encrypted files folders ‘© Copyright 1974 to current year. 57 AVEVA Solutions Limited and its subsidiaries. Al rights reserved.AVEVA Plant (12.1) ‘System Administration (Advanced) TM-1301 ga Batch File 5.6.3 Testing u It Is recommended that a batch file be created to encrypt the PML files. In this example a simple batch file will be written to test each option. In a suitable text editor open the batch fle, enerypt.bat, in the folder C:\testencrypt most of the lines are commented out using rem with the exception of the second to last line which would display help. Keep the file open for editing. Ensure all of the sub-folders in the C:\testencryptipmilib-encrypt folder are empty. 5.6.4 Testing the None Option ‘The first test uses the —none option on the area.pmifne file to see if the encryption process is working. The encrypt batch file needs to be edited (remove ‘rem’) to allow this line of the file to be run. The batch file should look like this: Run the batch file by locating encrypt.bat with Windows Explorer then double clicking on it. A cmd window will be displayed. To check the result, navigate to the C:\testencryptipmllib-encrypt\functions folder and edit the area.pmifne. The function should look like ths: The file is not encrypted but a header is added to the macro. ‘© Copyright 1974 to current year. 58 AVEVA Solutions Limited and its subsidiaries. All rights reserved,AVEVA Plant (12.1) ‘System Administration (Advanced) TM-1301 5.6.5 Testing the Trivial Option Edit encrypt.bat and enter rem at the start of the line containing the none option. Remove the rem from the start of the line containing the trivial option. The batch file should look like this: Save the file and double click on it to run the encryption. The file, hello.pmifrm, has been encrypted using the -trivial option. Navigate to the C:\testencryptipmilib-encryptiforms folder and edit the hello.pmifrm. The function should look like this: mains aed tee ante Meee aa SSeiser srcr yi" sist SD teytdoes! ayes core Note that the file is readable backwards, i.e. mrof putes is setup form. 5.6.6 Encrypting Multiple Files Al files with valid pml extensions can be encrypted in one command using the ~pmllib option. Edit the encrypt .bat file by entering rem at the start ofthe line containing the trivial option. Remove the rem from the start of the line containing the re4 pmilib option. The batch file should look like this: Save the file and double click on it to run the encryption. Navigate to each of the sub-folders of pmillib-encrypt and note that all pml files have been encrypted with the exception of NZONE as this does not have a valid pmi fle extension. All Files without a valid pml extension can be encrypted in one command using the ~folder option, however, care must be taken using this option as some files may not be pml macros. ‘© Copyright 1974 to current year. 59 AVEVA Solutions Limited and its subsidiaries. All rights reserved,AVEVA Plant (12.1) ‘System Administration (Advanced) TM-1301 Edit the encrypt .bat file by entering rem at the start of the line containing the rc4 pmilib option. Remove the Fem from the start of the line containing the re4 folder option. The batch file should look like this: Save the file and double click on it to run the encryption. Navigate to the macro sub-folder of pmillib-encrypt and note that the file NZONE has now been encrypted. 5.6.7 Testing Encrypted Macros When PDMS recognises an encrypted macro it is decrypted in memory as it is used. In this section the encrypted macros will be tested. In order to test the encrypted macros the pointer to pmllib must be changed to point to a multi path, Edit the file evars.bat. This batch file can be found in the %PDMSEXE% directory typically CAAVEVA\PlantiPDMS12.1.SP2. Close to the bottom of the file add the line: set pmilib=C:\testencryptipmilib-encrypt Yepmilib% lank Line Make sure there is a 2! unin cumvinimmsenrneninewmniins | atthe Bottom of the fle. Save the file and close the editor. Enter PDMS using the following options: Project Training, Username A.PIPER, Password A, MDB /A-PIPING, Module Design @® Ensure DAC is tured off. 5.6.7.1_Checking the pmilib Path The environment variable pmilib should now be set to a multi-path that includes the C:\testencrypt folder. Open the Command Window and enter Q EVAR PMLLIB. | QEVAR PMLLIB Environment variable PMLLI8 :C:Mtestencryptipmilib-encrypt C:\AVEVAIF * The file pml.index needs to be updated to include the new files in the extended path. Enter PML REHASH ALL in the Command Window to regenerate the file. If further files are encrypted the file should be refreshed using this command ‘© Copyright 1974 to current year. AVEVA Solutions Limited and its subsidiaries. All rights reserved,