Disclaimer This document is for informational purposes only and is subject to change without notice. This document and its contents, including the viewpoints, dates and functional content expressed herein are believed to be accurate as of its date of publication. However, Epicor Software Corporation makes no guarantee, representations or warranties with regard to the enclosed information and specifically disclaims any applicable implied warranties, such as fitness for a particular purpose, merchantability, satisfactory quality or reasonable skill and care. As each user of Epicor software is likely to be unique in their requirements in the use of such software and their business processes, users of this document are always advised to discuss the content of this document with their Epicor account manager. All information contained herein is subject to change without notice and changes to this document since printing and other important information about the software product are made or published in release notes, and you are urged to obtain the current release notes for the software product. We welcome user comments and reserve the right to revise this publication and/or make improvements or changes to the products or programs described in this publication at any time, without notice. The usage of any Epicor software shall be pursuant to an Epicor end user license agreement and the performance of any consulting services by Epicor personnel shall be pursuant to Epicor's standard services terms and conditions. Usage of the solution(s) described in this document with other Epicor software or third party products may require the purchase of licenses for such other products. Where any software is expressed to be compliant with local laws or requirements in this document, such compliance is not a warranty and is based solely on Epicor's current understanding of such laws and requirements. All laws and requirements are subject to varying interpretations as well as to change and accordingly Epicor cannot guarantee that the software will be compliant and up to date with such changes. All statements of platform and product compatibility in this document shall be considered individually in relation to the products referred to in the relevant statement, i.e., where any Epicor software is stated to be compatible with one product and also stated to be compatible with another product, it should not be interpreted that such Epicor software is compatible with both of the products running at the same time on the same platform or environment. Additionally platform or product compatibility may require the application of Epicor or third-party updates, patches and/or service packs and Epicor has no responsibility for compatibility issues which may be caused by updates, patches and/or service packs released by third parties after the date of publication of this document. Epicor is a registered trademark and/or trademark of Epicor Software Corporation in the United States, certain other countries and/or the EU. All other trademarks mentioned are the property of their respective owners. Copyright Epicor Software Corporation 2014. All rights reserved. No part of this publication may be reproduced in any form without the prior written consent of Epicor Software Corporation. Revision: February 03, 2014 10:27 a.m. Total pages: 18 sys.ditaval
Contents Contents...4 Integration Details...4 iscala User Permissions and Impersonation...5 Create User Account For Use by BAQ Service...5 Create a User to be Impersonated from ICE3 Extend...6 Secure Authentication Using SSL...7 Add Https Binding to Site...7 Importing IIS Certificate...8 DCOM Permissions...8 Datasource Type...8 Example...8 DataSource...9 Example...9 Company...10 Example...10 General Settings...10 Enable External Datasource...11 Business Activity Query...12 Example...12 Create New Query...12 Select Table and Fields...13 Execution Settings...13 Define Updatable Properties...14 Retrieve BAQ Results...15 Update Records...15 Importing iscala Users to ICE3 Extend...16 Limitations...17 3
This section contains information specific to using ICE Extend with iscala. Integration Details ICE3 Extend uses WCF services exposed from iscala installation to integrate with iscala. In order to access the structural information of iscala database, ICE3 Extend's BAQ (Business Activity Query) sub-system uses Business Data Dictionary Service exposed by iscala. The service is installed by iscala Server installer when Business Query WCF Services feature is selected to be installed. In order to access this service, the BAQ engine needs to authenticate in iscala; authentication of the user accessing the information is not required. In order to check or run BAQs against iscala business data, ICE3 Extend's BAQ sub-system uses Business Query Service exposed by iscala. The service is installed by iscala Server installer when Business Query WCF Services feature is selected to be installed. In order to access this service, the BAQ engine needs to authenticate in iscala and subsequently impersonate the user (from iscala point of view) accessing the data, so that queries are executed on behalf of the user and not on behalf of the account BAQ subsystem uses. Updatable BAQs invoke Service Connect workflows in order to apply updates. Therefore, when the updatable BAQ is created or is being edited, it attempts to create or update the workflow definition, as well as its request/response schemas. In order to create and update the workflow, BAQ sub-system uses two WCF services exposed by iscala installation: UBAQ Workflow Generation Service, which is installed when the corresponding feature is installed on iscala Server (this feature is subject to iscala license). UBAQ Workflow Generation Service is used to generate a new or updated workflow definition. Accessing UBAQ Workflow Generation Service does not require any authentication, as this service does not change anything in iscala installation. BPM Integration WCF Service which is installed when the Integration WCF Services feature is installed on iscala server. BPM Integration WCF Service is used to retrieve and save the updated workflow definition. Usage of this service requires that BAQ sub-system authenticates in iscala; user authentication is not required. When the data change is attempted to be applied by the user through Updatable BAQ, BAQ sub-system generates and posts the message to the Service Connect workflow which is specified in the corresponding UBAQ. To do so, it uses BPM Integration WCF Service, and in order to access it, it needs to authenticate in iscala's Service Connect. User authentication is not performed. Note Please be aware of the following limitation. Update messages posted to iscala from BAQ subsystem are applied on behalf of the user configured in the workflow for the corresponding manager, impersonation of the user requesting the update is not performed. 4
iscala User Permissions and Impersonation The following topics discuss the required iscala user permissions to work with ICE3 Extend BAQ engine. Create User Account For Use by BAQ Service Navigate to the iscala Administation Console. 1. Within the Security > Users node, create a New User which will be used by ICE3 Extend's BAQ engine. Example Field Name Full Name Description Alias Password Example BAQSvc ICE3 BAQ Engine ICE3: Account to be used by BAQ Service to call into iscala BAQSVC <password as per the organization policy> 2. Within the Security > Granted Permissions node, Add New Role. 3. Enter a name of the new role. Example ICE3 - BAQ Service. 4. Grant the following permissions: Permissions Developer > Manage Workflows System > General > System Logon System > Special > Impersonate Other Users 5. Within the Security > Enterprise Organigram node, Add New OrgNode. 6. Enter a name of the OrgNode. Example BAQ Integration Service. 7. Add new Associated User you created in step 1. Example BAQSvc. 5
8. Within the Security > Role Assignment, select the BAQ Integration Service OrgNode and map ICE3 - BAQ Service role to it (in all companies). Using the following example, specify BAQSvc account in ICE3 Extend's Data Sources and for launching SC Workflows in UBAQs. Create a User to be Impersonated from ICE3 Extend Create and set up rights for a user to be impersonated from ICE3 Extend. Since ICE3 Extend comes with a pre-defined user called Manager, the account matching it in iscala is created as an example. Navigate to the iscala Administation Console. 1. Within the Security > Users node, create a New User with the name matching one of ICE3 Extend's. Example Field Name Full Name Description Alias Password Example Manager Manager ICE3: Manager user MANAGER <password as per the organization policy> 2. Within the Security > Granted Permissions node, Add New Role. 3. Enter a name of the new role. Example ICE3 - BAQ Users. 4. Grant the following permissions: Permissions General > System Utilities > Run Queries Through Web Service System > General > System Logon 5. Within the Security > Enterprise Organigram node, Add New OrgNode. 6. Enter a name of the OrgNode. Example BAQ Users. 7. Add new Associated User you created in step 1. Example Manager. 6
8. Within the Security > Role Assignment, select the BAQ Users OrgNode and map ICE3 - BAQ Users role to it (in all companies). An internal iscala user with the name matching the user's User ID in ICE3 now exists in iscala. Secure Authentication Using SSL ICE3 Extend authenticates in iscala using UserName/Password credentials. For this to work, https protocol should be enabled in the IIS site hosting iscala WCF services. Enabling the https protocol also requires specifying the certificate to be used for data encryption by IIS. Add Https Binding to Site Verify that there is a certificate with the Issued To matching the full domain name of the server (or the name used to access the server in case a non-default web site is used) and that has the "Ensures the identity of a remote computer" property. To check it's properties, right-click the certificate and select View. If there's no such certificate, either create a self-signed certificate or request a certificate from the IT department. Use the following steps to enable the https protocol to be used on the site hosting iscala's WCF services. 1. Navigate to IIS Manager. Example Start > All Programs > Administrative Tools > Internet Information Services (IIS) Manager 2. In the Connections pane, expand the Sites node. 3. Select the site hosting WCF Services. Example Default Web Site. 4. In the Actions pane, click Bindings. 5. In the Site Bindings window, click Add. The Add Site Bindings window displays. 6. In the Type field, select https. 7. In the SSL certificate field, select the certificate you wish to use for the site. 8. Set up the remaining fields as desired and click OK. 9. In the Site Bindings window, click Close. 7
Importing IIS Certificate In order for ICE3 Extend to be able to access iscala's WCF Services, the server hosting ICE3 Extend's server side needs to know the certificate used by iscala server IIS's https binding. If ICE3 Extend's Server is installed on a different server than iscala, export the certificate from iscala Server and import it to certificates on ICE3 server. Otherwise - verify that the certificate is present in corresponding certificate branches on the shared server. DCOM Permissions In order for iscala WCF services to be able to access iscala, the account under which their back-ends run (Business Query Services and BPM Integration WCF Service use the application pool EpicorSCPool which is configured to use NetworkService by default) needs to have rights to access iscala services locally. This account should have Local Access, Local Activation and Local Launch permissions in DCOM Security (which can be configured in Windows' Administrative Tools\Component Services). DCOM Security Limits should not prevent the above permissions from being applied. Datasource Type Use External Datasource Type Maintenance to create a datasource type for iscala integration. Example Navigate to External Datasource Type Maintenance. Menu Path: ICE External > Setup > Datasource Types Important This program is not available in the Epicor Web Access. 1. Click New. 2. In the Datasource Type field, enter a unique identifier of the datasource type. Example iscala Data Source Type. 3. In the Application Type field, select iscala. This field determines that on updatable BAQ creation, the iscala generic workflow will be created in Epicor Service Connect to perform updates to the target database. 4. In the Description field, enter a brief description of the datasource type. Example Data Source Type governing iscala access. 8
DataSource Example Use the External Datasource Maintenance to establish connection between ICE Extend and iscala. In this example, create a datasource to establish connection to the iscala database. Navigate to External Datasource Maintenance. Menu Path: ICE External > Setup > Datasources Important This program is not available in the Epicor Web Access. 1. Click New. 2. In the Datasource field, enter a unique identifier of the iscala datasource. Example iscala DataSource. 3. In the Description field, enter a description of the external datasource. Example iscala DataSource pointing to iscala install on <ServerName>. 4. In the Datasource Type field, select a datasource type you previously set up. Example iscala Data Source Type 5. Navigate to the Distribution sheet. 6. Enter the following information: Field iscala Server Client ID Client Secret Value Enter the full domain name of the iscala server (or the name for which https binding of IIS hosting iscala WCF services is configured). Enter the user name to be used by BAQ engine to authenticate in iscala. Enter the password configured in iscala for the above user. 7. Click Test connection. You should be prompted with a message that the test was successful. 8. Click OK. 9. Click Save. Important Once you create a new datasource, you must enable it for each company you wish to use within your ICE Extend installation. 9
Company Use Company Configuration to define the primary settings for your iscala company. The ICE3 database is delivered without any pre-installed companies. To create a new company, use the Epicor Administration Console. You can then display the new company in ICE Extend and configure it as necessary. Tip For more information on how to configure the Epicor Administration Console and how to set up a new company, review the Epicor ICE Extend Installation guide. Example This example discusses the configuration options you can use to set up the desired functionality of your company. Navigate to Company Configuration. Menu Path: ICE External > Setup > Company Maintenance Important This program is not available in the Epicor Web Access. General Settings On this sheet, you can modify the name of the company you're currently logged into, set up the Enterprise Search parameters, Epicor Web Access settings, and specify Epicor Service Connect server options and a default workflow package you want to use for this company when creating updatable Business Activity Queries. 1. Navigate to the General settings sheet. 2. If you wish to utilize Enterprise Search in your environment, enter the Search URL in the below format. Example http://searchservername:9098/search/searchindexname If your search server name was EpicorApps and your search index name was default, the URL would be http://epicorapps:9098/search/default 3. To indicate the Search URL is the global location for the Enterprise Search program for all the companies within your organization, select the Global URL check box. You can then search for records located within other companies. 4. If you wish to launch the ICE Extend application within a web environment using the Epicor Web Access functionality, in the Web Access URL field, enter the URL of the Epicor Web Access application. Example The format looks as follows: http://<yourservername>/epicorwebaccess/default.aspx Tip You can obtain this information by browsing the Epicor Web Access site in Internet Information Services Manager (IIS7). 5. In the MetaData OutPut Path field, enter the location where metadata generated through the Epicor Web Access environment is stored. This metadata is required for the Epicor Web Access forms to run properly. 10
Example C:\Inetpub\wwwroot\EpicorWeb Tip You can obtain this information by exploring the Epicor Web Access site in Internet Information Services Manager (IIS7). Tip Users must be given permissions to display dashboards in this format. You do this within User Account Maintenance by selecting the Allow Epicor Web Access check box on the Options sheet. Once they have these rights, users can navigate their web browsers to the web address defined on this Epicor Everywhere sheet. 6. If you wish to perform Prophet 21 database updates using updatable Business Activity Queries and dashboards, you must set up Service Connect parameters. Field Server User Password UBAQ Workflow Package Value Enter the full domain name of the iscala server (or the name for which https binding of IIS hosting iscala WCF services is configured) Enter the user name to be used by BAQ engine to authenticate in iscala Enter the password configured in iscala for the above user. Select the package to use by default when creating SC workflows for updatable BAQs. This field determines the default workflow package for workflows created using External Business Activity Query Designer. You can, however, override this value when creating a new BAQ. 7. Click Test Connection to verify your connection to Service Connect server is established. 8. Click Save. Enable External Datasource On this sheet, enable the datasource(s) you created to access the specific Prophet 21 SQL database. 1. Navigate to the BAQ External Datasources sheet. 2. In the Datasources grid, the list of available datasources available for the company displays. Example iscala 21 DataSource 3. Select the Enabled check box for each datasource you want to make available within the current company. Important Do not skip this step! Only the datasources you enable become available for selection in External BAQ Designer. 4. Click Save. Tip On this sheet, you can also modify security settings applied to external datasources. 11
Business Activity Query Use the External Business Activity Query (BAQ) Designer to create personalized queries against the Prophet 21 database or to copy system queries so you can modify them. You access queries in different ways - use queries to create custom dashboards, include them in searches, or view and update queries through a dashboard or mobile device. Leveraging this functionality does require some fundamental knowledge of iscala database concepts such as table relationships, records, and field types. This knowledge helps you create queries that perform well and display the results you want. You start by defining the information to display through your BAQ, and then finding out which database tables or updatable views contain the appropriate columns which hold this data. Besides using BAQs to display custom views of data, users can also enter data directly within business activity queries. These updatable queries utilize events inside Epicor Service Connect workflows so users can create and edit records updating the database through the query itself. You create updatable BAQs in a similar way to display-only BAQs by adding tables, views, filter criteria, display columns, and so on. You have some extra steps, however, as you need to define which view contains the updatable fields. Tip For more info on using BAQS, review the External Business Activity Query Designer topics within the Application Help. Example In this example, learn how to create a simple updatable BAQ to retrieve and update the list of iscala customers. Important Log on to ICE3 Extend Client with the user account matching the account of the user present in iscala. Example Log in as manager. Navigate to Business Activity Query. Menu Path: ICE External > Operations > Business Activity Query Important This program is not available in the Epicor Web Access. Create New Query 1. Click New. 2. In the Query ID field, enter a unique identifier of the query. Example iscalacustomers Note Query ID can not exceed 30 characters. 3. Enter a brief Description of the query. Example iscalacustomers. 12
4. Select the Shared check box. The Shared check box indicates that this query is available to all users. 5. Select the Updatable check box. This indicates that users can update the target database using the BAQ and activates the sheets under the Update tab. 6. In the External Datasource field, select a valid datasource that provides connection to the iscala database. Example iscala DataSource. 7. Click Test Connection to verify the connection to the iscala is successful. 8. Click Save. Select Table and Fields 1. Navigate to the Query Builder > Phrase Build sheet. 2. In the Filtering field, enter SL. The list tables displays. 3. Double-click the SL01 table (Customer File) to add it to the design surface. 4. Navigate to the Display Fields > Columns Select sheet. 5. If necessary, double-click the SL01 node to expand it. 6. Move the following fields into the Display Column(s) section using the right blue arrow. Tip To select multiple columns, press and hold Ctrl to select the columns. Field Name SL01001 (CustomerCode) SL01002 (CustomerName) SL01003 (AddressLine1) 7. Click Save. Execution Settings Important In order to specify the iscala Company and Year for the BAQ to use, select Actions > Execution Settings in the form's main menu and specify the company code and financial year in _ext_company and _ext_year respectively. 1. Click Actions > Execution Settings. The Query Test Execution Settings window displays. 13
2. For the _ext_company field, enter a Setting Value to specify the iscala company code. Example D2 3. For the _ext_year field, enter a Setting Value to specify the financial year for which you want to run the BAQ. Example 2013 4. Click OK to close the Query Test Execution Settings window. 5. Click Save. Define Updatable Properties Use the controls on the Update > General Properties sheet to identify which fields are available to update on the Business Activity Query (BAQ). 1. Navigate to the Update > General Properties sheet. 2. Verify the Allow New Record check box is selected. 3. Select the Check All Fields as Updatable check box to allow updates to all selected fields within the BAQ. Tip You can decide to only make certain fields updatable. In order to do that, leave the Updatable check box clear and select the Updatable check box for each field you want to make updatable. 4. Click Save. 5. Navigate to the Update > Update Processing sheet. 6. You can either: Click New. In the Enter Workflow window, verify the default workflow package displays or select a different workflow package you want to use for this particular workflow. In the Enter new Workflow name field, enter a name for the customer list workflow. Tip Epicor recommends the BAQ and the workflow name be the same. Example iscalacustomers. Click Configure to create a new workflow using the Select Workflow window and if necessary, set up SC Workflow launch credentials. 7. Click Save. 14
Retrieve BAQ Results 1. Navigate to the Analyze sheet. 2. Notice the Updatable Query buttons found at the bottom of this sheet which call related methods in the generic service connect workflow: Get List - Executes the updatable BAQ to return a list from the database. Update - Writes the new changes to the query and refreshes the list with the next Get List. Get New - Runs a separate section and produces a new row at the bottom for updated information. Run Custom - If you created custom actions for the updatable query and then used the Updatable BAQ Method Directives program to set up conditions linked to this action, you can test this directive. 3. Click the Get List button and respond OK to the warning message. Notice the list of all customers displays in the grid. Update Records Test the BAQ to find out if you can update existing records. 1. Double-click a row within the Query Results grid. The Fields window displays. Note Notice this window contains all the fields you indicated were updatable on the Update > General Properties sheet. 2. Enter a new value in one of the fields. Example Change the customer's address. 3. Click OK. The updated line turns green and the non-updated fields turn yellow. 4. To save this change to the database, click the Update button. 5. To the warning message, click Yes. 6. In the Query Execution Messages pane, verify the Updatable query action fulfilled and reported no error message displays. 7. Click Get List to retrieve the data again and verify that the update was applied. Address any issues, if necessary. 8. Click Save. Example You can now use the updatable BAQ to create a dashboard and make it available to users using the Epicor ICE smart client, Epicor Mobile Access, Epicor Web Access or Microsoft SharePoint. 15
Importing iscala Users to ICE3 Extend This topic outlines how to import iscala internal users to ICE3 Extend. Log into ICE 3 Extend. 1. Create a new Datasource Type using the following attributes: Field Datasource Type Application Type Description Value iscalasystemdb Generic iscala System Database 2. Create a new Datasource using the following attributes: Field Datasource Description Datasource Type ADO.NET Provider Value iscalasystemdb iscala System Database ScalaSystemDB SqlClient Data Provider 3. Click Configure and in the MS SQL Connection Parameters dialog, specify the following: Field Data Source Database name Authentication Value The name of the SQL Server (or instance) hosting iscala System Database. The name of iscala System Database. Set up the authentication to allow ICE3 Extend's server access the DB. The simplest way is to use SQL Server credentials, if they are enabled on the target SQL Server. 4. Click Test Connection to verify the connection is successful. 5. In Company Maintenance, on the BAQ External Datasources sheet, enable the data source you created. Tip In order to avoid opening iscala System Database access to all ICE3 users, disable the data source after user import is completed. 6. When importing users from iscala, Epicor Administration Console needs an existing ICE3 user to use as a template. If such user does not exist, create one using User Account Maintenance. 7. In the External Business Activity Query Designer, click Actions > Import BAQ option to import the iscalausers BAQ shipped with the product. 16
8. When prompted to specify the external data source for the BAQ, select iscalasystemdb. Important The backup of iscalausers BAQ is found in the following location <iscala installa tion folder>\tools\contentpacks\ice\userimport\ 9. In the Epicor Administration Console, navigate to:server Management > <ICE3 Extend server name> > <ICE 3 Extend Application Server Name> > Users 10. On the Actions pane, click Import External User(s) and follow the wizard. 11. When prompted for the BAQ to use, select the iscalausers BAQ you imported. Note Please be aware of the following limitation: Only iscala internal users can be imported to ICE3 Extend. Limitations Please be aware of the following limitations in the current release of ICE3 Extend application: Update messages posted to iscala from BAQ subsystem are applied on behalf of the user configured in the workflow for the corresponding manager, impersonation of the user requesting the update is not performed. Authenticating ICE3 Extend users in iscala as Windows users is not currently supported. 17
Additional information is available at the Education and Documentation areas of the EPICweb Customer Portal. To access this site, you need a Site ID and an EPICweb account. To create an account, go to http://support.epicor.com.