FlexSync Foundation User Guide
Extensibility
Pack 3.5
E42085-01
August 2013
Agile Product Lifecycle Management for Process
Copyright © 1995, 2013, Oracle and/or its affiliates. All rights reserved.
This software and related documentation are provided under a license agreement containing restrictions on use and disclosure and are protected by intellectual property laws. Except as expressly permitted in your license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license, transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means. Reverse engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is prohibited.
The information contained herein is subject to change without notice and is not warranted to be error-free. If you find any errors, please report them to us in writing.
If this is software or related documentation that is delivered to the U.S. Government or anyone licensing it on behalf of the U.S. Government, the following notice is applicable:
U.S. GOVERNMENT END USERS: Oracle programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, delivered to U.S. Government end users are "commercial computer software" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, use, duplication, disclosure, modification, and adaptation of the programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, shall be subject to license terms and license restrictions applicable to the programs. No other rights are granted to the U.S. Government.
This software or hardware is developed for general use in a variety of information management applications. It is not developed or intended for use in any inherently dangerous applications, including applications that may create a risk of personal injury. If you use this software or hardware in dangerous applications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure its safe use. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of this software or hardware in dangerous applications.
Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners.
Intel and Intel Xeon are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks are used under license and are trademarks or registered trademarks of SPARC International, Inc. AMD, Opteron, the AMD logo, and the AMD Opteron logo are trademarks or registered trademarks of Advanced Micro Devices. UNIX is a registered trademark of The Open Group.
This software or hardware and documentation may provide access to or information on content, products, and services from third parties. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to third-party content, products, and services. Oracle Corporation and its affiliates will not be responsible for any loss, costs, or damages incurred due to your access to or use of third-party content, products, or services.
Contents
Modifying Existing Report Templates
Appendix B: What did the Installer do?
Appendix C: FlexSync Configuration Utility
Appendix D: Entity Relationship Diagram (ERD)
This guide is intended for client programmers involved with integrating Oracle Agile Product Lifecycle Management for Process. Information about using Oracle Agile PLM for Process resides in application-specific user guides. Information about administering Oracle Agile PLM for Process resides in the Oracle Agile Product Lifecycle Management for Process Administrator User Guide.
Descriptions and illustrations of the Agile PLM for Process user interface included in this manual may not match your installation. The user interface of Agile PLM for Process applications and the features included can vary greatly depending on such variables as:
• Which applications your organization has purchased and installed
• Configuration settings that may turn features off or on
• Customization specific to your organization
• Security settings as they apply to the system and your user account
For information about Oracle's commitment to accessibility, visit the Oracle Accessibility Program website at http://www.oracle.com/pls/topic/lookup?ctx=acc&id=docacc.
Oracle customers have access to electronic support through My Oracle Support. For information, visit http://www.oracle.com/pls/topic/lookup?ctx=acc&id=info or visit http://www.oracle.com/pls/topic/lookup?ctx=acc&id=trs if you are hearing impaired.
Oracle Software Delivery Cloud (OSDC) provides the latest copy of the core software. Note the core software does not include all patches and hot fixes. Access OSDC at:
http://edelivery.oracle.com
FlexSync Foundation provides the platform necessary to create, manage, and orchestrate reports. You will have the ability to export relevant data to a customized Excel user interface with macros, manipulate the data based on business needs, and then import the data back into PLM4P to maintain your single source of truth.
Figure 1. FlexSync Foundation
· Chains of data handlers allow data to be pulled/pushed via a variety of mechanisms allowing for unlimited extensibility
· Oracle-provided general purpose handlers provide out of the box functionality
· Reusability of out of the box templates. Templates can be modified to provide additional functionality without the need for a developer to create new handler chains.
· Table based report configuration allows for easy report creation/maintenance
This guide will help you install, configure, and gain a basic understanding of how to use FlexSync Foundation.
FlexSync may not always be the correct solution to a given business problem. To assist in your evaluation, answer the following questions and review the problem examples.
· What is the current business problem?
· How is it currently being solved?
· Can this be solved using the PLM4P UI?
· Can this be solved with other extensions?
Problem |
Possible Solution |
I want to compare costs across facilities for this formulation. |
Contextual Reporting |
I need to see which % of this formulation is sweetener versus a solvent. |
Calculated Extended Attributes and Tags |
I am used to seeing Calories, Fat and Acidity as I formulate. I use these as targets and they help me understand which quantities to use. |
Extensible Columns |
I need to see my formulation in kilograms, pounds, gallons and liters |
Contextual Reporting |
I need to see the calculated volume for each input as a formulate. |
Extensible Columns |
I need to automatically update my input quantities based on other calculations. For example, I need the weight of my water input to be adjusted based on a user entered extended attribute “Acidity” amount. |
FlexSync |
I need to create multiple prototypes in one location and quickly compare values across them as I change quantities. |
FlexSync |
Complete the following steps to install FlexSync Foundation:
Version 6.1.1 is required before installing.
1. Unzip package to a temporary location.
Ex. c:\tmp\FlexSync
2. Backup the database.
3. Run ApplyScripts.exe package against the PLM4P database (See “ApplyScripts” section below for detailed instructions).
4. Run FlexSyncFoundationSetup.exe to initiate the FlexSync Foundation Installer (when prompted for IIS details, ensure the values entered are correct).
To run ApplyScripts, follow these steps.
1. Open a command prompt.
2. Change directory to Scripts directory of this patch.
prompt> cd C:\FlexSync\ApplyScripts\
3. Call ApplyScripts.exe with correct parameters:
-c connectstring (copy from environmentvariables.config)
-f filename (MS SQL ex. -f FlexSync.xml) (Oracle ex. -f FlexSync-orcl.xml)
-dbvendor dbtype (MS SQL ex. -dbvendor msft) (Oracle ex. -dbvendor orcl)
ex. MSSQL prompt> ApplyScripts.exe -c
"server=customerServer.domain.com;uid=UserName;pwd=Password;database=prodikaCatalog"
-f FlexSync.xml -dbvendor msft
ex. ORCL prompt> ApplyScripts.exe -c "user id=user;password=password;data source=PLM4P"
-f FlexSync-orcl.xml -dbvendor orcl
FlexSync Report creation begins with creating a Report Template. This template spreadsheet defines how the report will be laid out and what information it will contain. It consists of a standard Excel spreadsheet with named range definitions to drive where imported data is placed. There are no restrictions on how this template file is structured, but all cells that are to be populated with exported data will require being set as named ranges. When exporting collections of data and multiple rows of are expected, the named range need only contain a single row. The FlexSync Foundation exporter will automatically expand the number of rows in the named range as necessary depending on the collection size. Please see the Microsoft Excel documentation for direction on creating and managing named ranges within an Excel spreadsheet.
Currently, you can create new report templates by copying an existing template and modifying the working sheet. For example, as part of the FlexSync Formulation Solution Pack, we provide report templates that export formulation data to excel. You can copy one of these templates, modify the working sheet, and then add a navigation extension to launch the report within GSM.
We ask that you do not modify the ‘From PLM4P’ or ‘To PLM4P’ worksheets.
Warning: Please note that FlexSync Foundation uses document properties to track the report used to generate the spreadsheet as well as the report generation timestamp. Deletion of the document properties can prevent subsequent attempts to import data back into PLM4P.
Once you have installed a FlexSync Solution Pack such as FlexSync Formulation, you can create a new report by copying an existing template. For more information, see Appendix C: FlexSync Configuration Utility.
1. On the application server, copy MyNewReport.xlsm to C:\Prodika\Templates\
2. Browse to PRODIKA_HOME\Apps\SolutionPacks\FlexSyncConfig\
3. Edit FlexSyncConfig.exe.config and enter a valid connect string for your DB.
4. Open FlexSyncConfig.exe.
5. Click Copy. This will create a new report as PrototypeExperimentPercentReport_copy. See Figure 2.
6. Click Edit with PrototypeExperimentPercentReport_copy highlighted. See Figure 3.
7. Give the report a new name like MyNewReport (no spaces).
8. Provide Template file path like C:\Prodika\Templates\MyNewReport.xlsm.
9. Commit your changes and export the report
This will create a SQL script that your DBA will need to execute against your PLM4P DB
Figure 2. Copy Report
Figure 3. Edit Report Summary
Before making a lot of code changes, please check the FlexSync Formulation Solution Pack User Guide. You may be able to solve your business problem with a few minor tweaks to the existing templates.
In normal course, FlexSync Reports are invoked using Menu Items or navigation icons that have been set up in the SiteMap-Extensions.xml file. To invoke a FlexSync Report manually, you will need to browse to the FlexSyncWorker.aspx page and specify both reportName and specid parameters. The reportName request parameter is used to specify the desired report and must exactly match the name of the request in the FlexSyncReport table. The specid parameter is the unique id of the specification upon which the report will be based. See the Navigation Configuration Guide for detailed information on how to add a menu item or navigation button to your specs. You can reference the entries in the SiteMap-Extensions.xml and SiteMap-DisplayOrder.xml files added by the FlexSync Installer as templates for adding additional report menu items.
Example call:
http://<server-name>/Flexsync/FlexSyncWorker.aspx?reportName=MyNewReport&specid=<unique-spec-id>
As new solution packs leverage the FlexSync Foundation, these templates can be modified to provide additional functionality without the need to create new handler chains. As long as the data is already exported, you can easily change the VBA functions to add new data to your working sheet.
Additional details can be found in the solution pack documentation.
To improve performance of the export process, you can remove named ranges deemed unnecessary to the business. These named ranges will then be ignored during the export process. For instance, the out of the box template exports distinct EAs. If the business does not need this data, then the section and the corresponding named ranges can be removed from the template. FlexSync checks the spreadsheet, and if the named range isn’t there, it will not export the data.
Certain fields exported to Excel could potentially be used to gain access to sensitive and confidential data within PLM4P. For this reason, we offer the ability to encrypt these key fields. In a future release, you will be able to add an out of the box intermediate handler, giving you the ability to quickly encrypt any field you mark as confidential. For now, only keys will be encrypted on export and then decrypted on import.
To disable encryption/decryption, set the following key value to false in your <FeatureConfig> node in config\custom\CustomerSettings.config file:
<add key="Flexsync.Encryptinternalids.Enabled" value="false" />
FlexSync encryption uses the DataExchange.Encryption.keyPassPhrase and DataExchange.Encryption.IVPassPhrase keys obtained from the Setup Assistant. Changing the encryption keys after an export will cause subsequent imports to fail.
FlexSync Import is the logical reversal of the spreadsheet data export provided by FlexSync. The user is allowed to upload a spreadsheet previously created via FlexSync export with updated values contained within the _import named ranges. At the time of export, the _import named ranges will be populated with the same data as the export fields upon which they are based. This provides a starting point for updating data. Changes to the _import named ranges will be pulled from the incoming spreadsheet and used to update the associated PLM4P object.
Fields intended to be used for import will need to have the ‘supportsImport’ property set for the field. They will also need to have handler chains that are composed of handlers with implemented Import() methods. Finally, import named ranges will need to be defined in the report template that follows the <field-name>_import naming convention.
After a FlexSync report has been exported, the user can change select data using the <field-name>_import named ranges. Any import named ranges that are left empty will be ignored by FlexSync when the spreadsheet is uploaded for import. If the intent is to set the field to blank or null (depending on type), use the string ‘NULL’.
The FlexSync import dialog allows the user to specify the intended import spreadsheet. The import button initiates the import process. Any import problems or data validation issues will be presented to the user directly in the import dialog.
Figure 4. Import User Interface
1. How do I verify FlexSync Foundation installed correctly?
You can check Appendix B of this guide to understand what the installer did. However, to date, we do not have a reference implementation, so you will have to install a FlexSync Solution Pack such as FlexSync Formulation to verify FlexSync Foundation installed properly.
2. If I need to contact support for an issue, what information should I provide them?
Depending on the type of issue, more information may be required, but at a minimum, you should provide any relevant event log entries from ‘Prodika’ and ‘FlexSync-Prodika’. If you receive a stack trace in IE, be sure to include this in text form, as well.
3. I see how to invoke a report, but how do I add a report to my specification?
You can create a menu item or a navigation icon. If you already installed FlexSync Formulation, and you wish to add to the existing list of menu item reports, you can copy what FlexSync Formulation did as part of its installation. You will need to modify config\extensions\SiteMap-DisplayOrder.xml and config\extensions\SiteMap-Extensions.xml. You may also need to add a custom translation to commonXLAExtensionCacheItem. For more information, see the Navigation Configuration Guide as part of the Extensibility Pack documentation on OTN.
4. What is the Entity Relationship Diagram (ERD) for FlexSync?
Please see Appendix D for the ERD.
The installer will perform the following tasks for you:
· Backup all affected files to PRODIKA_HOME\SolutionPacksBackup\FlexSync\FlexSyncFoundation
· Copy \FlexSync directory to PRODIKA_HOME\web\
· Copy new FlexSync*.dll to PRODIKA_HOME\web\gsm\bin\
· Copy FlexSyncConfig utility to PRODIKA_HOME\Apps\SolutionPacks\FlexSyncConfig\
· Create FlexSync-Prodika application event log
· Create FlexSync virtual directory under the GSM application in IIS
· Add the following key to customersettings.config\featureconfig
<add key="Flexsync.Encryptinternalids.Enabled" value="true" />
FlexSyncConfig Lite is a windows application to configure FlexSync reports. FlexSyncConfig Lite features include:
· Limited report editing
· Report copy, delete and export
The FlexSync Config Lite distribution includes a config file named FlexSyncConfig.exe.config. This file includes app settings for CONNECTION_STRING and DB_PROVIDER. CONNECT_STRING should be set to the connection string of the database that contains your FlexSync reports. DB_PROVIDER should be set to either msft or orcl depending on the vendor of your database.
The application is invoked as follows and does not require or support command-line parameters:
C:\>FlexSyncConfig.exe
The first window encountered when launching the FlexSyncConfig application is the Reports List dialog box.
Figure 5. Reports dialog box
You are provided a list of reports currently defined and the ability to:
• Select and edit an existing report
• Copy or delete an existing report
• Select and export the SQL necessary to completely generate a report (beneficial for exporting between systems)
• Export the SQL necessary to completely generate all the reports
When editing an existing report, the Report editor dialog box provides the ability to set report attributes.
Figure 6. Report Editor dialog box
CalculatePath, Post Import Handler Factory, and Post Import Handler Config parameters are used to govern what happens immediately after an import is completed. The Post Import handler returned from the specified factory is configured with the supplied parameters and executed after each import completes. If the object of interest is a formulation spec, the post-import handler may use the specified Calculate path to trigger a recalculate.
All changes to the report are saved when the Commit button is pressed. The user can reject any changes made to the report using the Cancel button.