version 12.16
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 2015. All rights reserved. No part of this publication may be reproduced in any form without the prior written consent of Epicor Software Corporation. - 2 -
Table of Contents 1 Overview 4 2 SSL Configuration for Prophet 21 Middleware 5 Primary Domain and Subdomains 5 SSL Recommendations 5 SSL Certificates in IIS 6 3 System Requirements 7 Hardware Requirements 8 4 Configure Server Roles 9 Configure Server Roles Using Windows Server 2008 R2 10 Configure Application Server Roles 10 Configure File Services Role 11 Configure Web Server Role 11 Configure Server Roles Using Windows 2012 13 5 Setting Up Your Server and Database 17 Create the EDS Database 18 Create New Logins 20 6 Installing the Middleware Framework 21 Configuring the Middleware Framework 26 7 Updating the Middleware 33 8 Program Menu Items 34 Configuration 35 Single Instance 35 Multiple Instances 35 Code Examples Application 36 Get 37 Update 38 Source Code for the Code Examples 39 Command Line Process of the Installation 39-3 -
1 Overview Before you can integrate any Prophet 21 Middleware products with your Prophet 21 system, you must install the Middleware framework. The Middleware framework consists of several software frameworks to support our software applications. These frameworks support communication between your production database and the central Middleware server. If you are not running any of these products, you do not need the Middleware. This manual describes the process of installing and configuring the Middleware framework for your production system. There are three parts to the installation. Setting up your server and database Installing the Middleware components Configuring your Middleware framework The following chapter explains the process in detail with step-by-step instructions. - 4 -
2 SSL Configuration for Prophet 21 Middleware There are several approaches to configuring security in your Middleware. There are many different variables involved in requesting an SSL certificate from a Certificate Authority (CA) such as Verisign or GoDaddy. Review this section for information on security your Middleware. Primary Domain and Subdomains More than likely, your company already has a domain (i.e. epicor.com) registered with a valid domain registrar. This is your primary domain, which you can use for your corporate website and email. A subdomain is a method to further organize web site content under your primary domain. Subdomains add a new level onto the front of your domain where a URL can rout traffic to either another website or directory under a website. For example, you could provide external access to your Middleware API using a subdomain such as: https://p21api.epicor.com This requires that you configure this subdomain to route to your Middleware API server via the external port configuration on which the API in running. SSL Recommendations Epicor recommends purchasing a valid SSL certificate from a trusted Certificate Authority rather than using a self-signed certificate. Self-signed certificate are fine for internal testing, but not for external public consumption, Epicor recommends purchasing a wildcard SSL certificate so that you can configure multiple websites with SSL. A wildcard SSL certificate protects your primary domain and an unlimited number of its subdomains. For example, a single wildcard certificate can secure https://www.mycompany.com, https://p21- mobile.mycompany.com, and https://p21api.mycompany.com. This will allow you to configure subdomains with a single certificate. - 5 -
SSL Certificates in IIS Middleware is hosted in Microsoft Internet Explorer (IIS). Documentation on how to generate an SSL certificate for IIS is available from Microsoft. In addition, Certificate Authorities, such as Verisign, GoDaddy, Network Solutions, all provide documentation and assistance for installing your SSL certificate. Epicor recommends following the instructions provided by your chosen CA. Once you have a valid SSL certificate generated and installed into IIS, the Middleware installation wizards will prompt you for which SSL certificate you wish to use. You can select the appropriate certificate and the installation will bind that SSL certificate to the appropriate HTTPS port. - 6 -
3 System Requirements Before you can install the Prophet 21 Middleware software, review the following prerequisites. Important! The user installing the Middleware must be part of the Windows domain. A server with SQL 2005 or later installed You can use your Prophet 21 production database server; the server should use the TCP / IP protocol for connections (you can view and change protocols using the SQL Server Configuration Manager) Server must be within Windows domain The Microsoft.NET Framework version 3.5 AND.NET Framework version 4.5 or later must be installed on the server A valid SSL certificate to be configured in IIS prior to performing the Middleware install. There are two types of certificates that can be utilized depending on how comfortable you feel with security inside your organization. If you don t have a certificate of your own, you can create a self-signed certificate in IIS. o o Certificate generated by an authorized Certificate Authority (CA) Certificate generated self-signed (IIS) Information on how to create a self-signed certificate can be found here: http://technet.microsoft.com/en-us/library/cc753127(v=ws.10).aspx Important! The Prophet 21 middleware depends on the Data Access Components from Microsoft and the latest version of these components has a known issue that does not allow remote code execution (MS12-045). Prior to utilizing the Prophet 21 Middleware, the following Microsoft hotfix must be applied to the server: http://support.microsoft.com/kb/2734642. - 7 -
Hardware Requirements Hardware Requirements Review the following hardware and size requirements for your server. Windows Server 2012 OR Windows Server 2008R2 1 CPU with 4 cores 8GB RAM 100GB disk space - 8 -
Hardware Requirements 4 Configure Server Roles Before installing or upgrading the Prophet 21 Middleware, you must configure server roles, including the Application Server, File Services, and Web Server. Use the following steps to configure Server Roles. Note that these steps may differ based on your environment. If the server roles already exist, you can still review the list of role features to verify that your roles are configured properly. - 9 -
Configure Server Roles Using Windows Server 2008 R2 Configure Server Roles Using Windows Server 2008 R2 Complete the steps in this section only if you are using Windows Server 2008 R2. If you use Windows Server 2012, refer to the steps in Configure Server Roles Using Windows 2012 on page 13. Configure Application Server Roles Complete these steps to configure the Application Server Role. 1. On the server, open Server Manager, and then select the Roles note. 2. In the Roles Summary section, verify that the Application Server role lists. a. If the role is listed, click Add Role Services and use the following steps to verify that the required Application Server role services are installed. b. If the role is not listed, click Add Roles, and then click Next. 3. On the Select Server Roles window, select Application Server. a. If the Add Roles Wizard opens, click Add Required Features to add any required, listed features. For example, you may need.net framework and Window Process Activation Services. Click Next. 4. On the Introduction to Application Server window, review the noted comments, and then click Next. 5. On the Select Role Services window,.net 3.5.1 is already selected. Select any of the addition options, including any of the following, and then click Next. 6. TCP Port Sharing Windows Process Activation Service Support Message Queuing Activation TCP Activation Named Pipes Activation Distributed Transactions Incoming Remote Transactions Outgoing Remote Transactions COM+ Network Access 7. Click Next, and then click Install. The Application Server Role and features install. 8. Once the installation completes, click Close. - 10 -
Configure Server Roles Using Windows Server 2008 R2 Configure File Services Role Complete the following steps to configure the File Services role. 1. On the server, open Server Manager, and then select the Roles node. 2. In the Roles Summary section, verify that Files Services lists. a. If the role is listed, click Add Role Services and use the following steps to verify that the required File Services role services are installed. b. If the role is not listed, click Add Roles, and then click Next. 3. On the Introduction to File Services window, review the notes, and then click Next. 4. On the Select Server Roles window, select File Services, and then click Next. 5. On the Select Roles Services window, enable the File Server check box, and then click Next. 6. Click Next, then click Install. The roles, role services, and features install. 7. Once the installation completes, click Close. Configure Web Server Role Complete the following steps to configure the Web Server role. 1. On the server, open Server Manager, and then select the Roles node. 2. In the Roles Summary section, verify if the Web Server role is listed. a. If this role is not listed, use the following steps to add the roles services. b. If the role is listed, click the Add Role Services link on the right side. Then use the step below regarding the Web Server dialog to verify that the required Web Server role services have been installed. 3. Click Add Roles, and then click Next. 4. On the Select Server Roles window, select Web Server (IIS), and then click Next. 5. On the Introduction to Web Services (IIS) window, review the noted comments and click Next. 6. On the Select Role Services window, select following options: Common HTTP Features: Static Content Default Document Directory Browsing HTTP Errors HTTP Redirection - 11 -
Configure Server Roles Using Windows Server 2008 R2 Application Development: ASP.NET.NET Extensibility ASP CGI ISAPI Extensions (if prompted to install dependencies, select Add Required Role Services and then continue) ISAPI Filters Server Side Includes Health and Diagnostics: Security: HTTP Logging Logging Tools Request Monitor Tracing Custom Logging ODBC logging Basic Authentication Windows Authentication Digest Authentication Client Certificate Mapping Authentication IIS Client Certificate Mapping Authentication URL Authorization Request Filtering IP and Domain Restrictions Performance Static Content Compression Management Tools IIS Management Console IIS 6 Management Compatibility 7. Click Next, and then, click Install. The roles, role services or features install. 8. Once the installation completes, click Close. - 12 -
Configure Server Roles Using Windows 2012 Configure Server Roles Using Windows 2012 Complete the steps to configure the Application Server role and Web Server role using Windows 2012. If you use Windows Server 2008 R2, refer to the steps in Configure Server Roles Using Windows Server 2008 R2 on page 10. Note that if the roles already exist, you can still review the list of role features to verify that your roles are configured properly. 1. On the server, open Server Manager. 2. In the left pane, select App Server. 3. In the Roles and Features section verify that Application Server and Web Server (IIS) Support list. a. If the Server roles list in the same Roles and Features section, verify that the required Server roles have been installed. Skip to step 11. b. If the Server roles are not listed, from the Manage menu, select Add Roles and Features. 4. On the Add Roles and Features window, in the Before you Begin section, review the information, and then click Next. 5. On the Installation Type window, verify that the default Role-Based or Feature-Based Installation option is selected, and then click Next. 6. On the Server Selection window, verify that your server is selected in the Server Pool list, and then click Next. 7. On the Server Roles window, select the Application Server role, File and Storage Services role, and the Web Services (IIS) role. Note that the IIS Management Console is required for the Web Server role installation 8. Click Add Features, and then click Next. 9. On the Features window, verify that.net Framework 4.5 is selected, and then click Next. 10. On the Application Server window, click Next. - 13 -
Configure Server Roles Using Windows 2012 11. On the Roles Services window, select the following options, and then click Next. COM+ Network Access TCP Port Sharing Windows Process Activation Service Support Message Queuing Activation TCP Activation Named Pipes Activation Distributed Transactions Incoming Remote Transactions Outgoing remote Transactions 12. On the File and Storage Service window, click Next. 13. On the Role Service window, select File and iscsi Services, select the File Server service to install, and then click Next. 14. On the Web Server Role (IIS) window, click Next. - 14 -
Configure Server Roles Using Windows 2012 15. On the Role Service window, select the Web Server and any of the following services to install. Then click Next. Common HTTP Features Default Document Directory Browsing HTTP Errors HTTP Redirection Static Content Application Development.Net Extensibility 3.5.Net Extensibility 4.5 ASP ASP.NET 3.5 ASP.NEt 4.5 CGI ISAPI Extensions ISAPI Features Server Side Includes Health and Diagnostics HTTP Logging Custom Logging Logging Tools ODBC Logging Request Monitor Tracing Performance Static Content Compression Dynamic Content Compression Management Tools IIS Management Console IIS 6 Management Compatability IIS Management Scripts and Tools - 15 -
Configure Server Roles Using Windows 2012 Security Request Filitering Basic Authentication Client Certification Mapping Authentication Digest Authentication IIS Client Certificate Mapping Authentication IP and Domain Restrictions URL Authorization Window Authentication 16. On the Confirmation window, click Install. The server roles and features install. 17. Once the installation completes, close the Server Manager. - 16 -
Configure Server Roles Using Windows 2012 5 Setting Up Your Server and Database To set up your server and database before you install the Middleware framework, you must do the following: Create the Middleware database Create two new logins for the Middleware framework (one to access the Middleware database, and one to access the Prophet 21 database) These instructions use SQL Server 2008. For more information on how create databases or logins for other versions of SQL Server, please refer to SQL Server Books Online. - 17 -
Create the EDS Database Create the EDS Database Important! This step is only needed if you are using the Service Dispatch product. If you are this, you can skip to the next step. 1. Log into the server you want to use for your Middleware database. This server may be your production database server or some other server you want to use for the Middleware. 2. Open SQL Server Management Studio (Start > All Programs > Microsoft SQL Server 2008 > SQL Server Management Studio). 3. Log into your server. 4. Expand the instance on which you want to install Middleware. Note: You may have only one instance, depending on how you set up SQL Server. 5. Right-click the Databases node and select New Database. 6. Name your database. Epicor recommends using EpicorDS. 7. To accept the rest of the defaults, click OK. Your database is created. - 18 -
Create the EDS Database After creating the database for the Middleware, you need to create SQL Server logins for the Middleware. - 19 -
Create New Logins Create New Logins The Middleware framework must have access to both its own database (above), and also to your Prophet 21 production database. 1. Open the SQL Server Management Studio on your Prophet 21 SQL Server. (Start > All Programs > Microsoft SQL Server 2008 > SQL Server Management Studio). 2. Expand the server to access the Security node. 3. Right-click the Security node and select New > Login. 4. On the General page, give the login a name. Epicor recommends epicorp21user. 5. Select SQL Server authentication. 6. Enter a secure password for the login. Make sure you track this login and password as you normally track secure logins to the database, as you will need to specify this later. 7. Disable the Enforce Password Policy check box. 8. Select Prophet 21 as the default database. 9. Select the Server Roles page. 10. Enable the sysadmin check box to give this login system administration privileges for the SQL Server. 11. Select the User Mapping page. 12. In the User mapped to this login area, select the Map check box to map epicorp21user to the Prophet 21 database. 13. If you are using the Dispatch product, repeat Steps 3-15, except the login name should be epicordsuser, and the database should be your EDS database. Otherwise, skip this step. After creating the SQL Server logins the Middleware framework, you can install the Middleware framework components. - 20 -
Create New Logins 6 Installing the Middleware Framework Note: Installing the Middleware framework may require you to restart your server, so plan accordingly. If you are using your production server, we recommend performing the installation during off-hours. 1. Log onto the server where you will be installing the Middleware software. 2. Download the Middleware installer from the Customer Web Site and make sure it is available to the server. 3. The Epicor.P21.Middleware.Install.xxx.exe file starts the installation. Right click and select Run as Administrator. - 21 -
Create New Logins 4. Click Next to continue the installation. 5. If you want to copy the settings from an existing instance to a new instance, enable Copy Existing Settings. 6. Provide the instance from which you are copying the settings. 7. Click Next to continue installation. - 22 -
Create New Logins 8. If you want to change the destination drive, use the drop down to select a location or type a new location. 9. Click Next to continue. - 23 -
Create New Logins - 24 -
Create New Logins 10. Click Install to install the Middleware framework components. The Middleware Configuration Wizard starts automatically. - 25 -
Configuring the Middleware Framework Configuring the Middleware Framework The Middleware framework's configuration tool opens automatically a few moments after the components installation is complete. This installation configures your Middleware framework so it can access the databases. 1. You are next asked for your subscriber domain. a. If you are installing the Middleware for the first time and only for use with the Prophet 21 Help, please use P21Help.edu (case sensitive) as the value. b. If you have previously installed the Middleware, your existing Domain Name will be shown. The Prophet 21 Help will be available for your subscriber domain. - 26 -
Configuring the Middleware Framework 2. Enter the name of the subscriber domain you received as part of the purchase of your Prophet 21 Middleware product. 3. If you use a proxy server, check the box and enter the proxy information. 4. Click Next to configure Prophet 21 Middleware database access. 5. Enter the server name, port, database name, user name, and password: 6. Click Next to continue. 7. Enter the server name, port, database name, user name, and password: - 27 -
Configuring the Middleware Framework Notes: The database and user name you enter here should be the same as those entered in the previous screen. This screen only appears if you have purchased the Proof of Delivery, Service Dispatch, or BPS products. 9. Click Next to Configure Network Security information (Windows Domain Server) The type of authentication selected determines the repository from which the application pulls login information. Your options in this screen are: - 28 -
Configuring the Middleware Framework Database Authentication- uses the user name and password from the SQL server login section Windows Authentication- uses the Windows login and password credentials of the person logged into the PC Note: If you are using Windows Authentication and are not logged in with a Network Login, enter the login name here. 10. Click Next to configure your Business Analyzer database. Note: This screen only appears if you purchase the MBA product. 11. Click Next to configure the ports over which the Middleware API will run. - 29 -
Configuring the Middleware Framework Important! If you have purchased the CPA\Datawarehouse product, make sure to copy the Api Consumer Shared Key displayed in the upper right of this screen to a file you can reference later. You will need it again. If you have not purchased that product, you do not need to record this key. 12. Click the... button to show an SSL certificate selection popup window. 13. Click OK to return to the API window, and Next to move to the next step. 14. You cannot edit the New and Current Web Help URL fields. - 30 -
Configuring the Middleware Framework Important! The setup reads the current Web Help URL field from your Prophet 21 database. If this is your first time configuring the web help, the URL field in your database will be empty. The New URL field is automatically formatted and populated for you. If the installation finds a value in your database, the database value displays in the Current field and a new URL displays in the New field. 15. To enable the web help in Prophet 21, select the Use Web Help in Prophet 21 check box. If you do not enable the web help, you will still be able to view the standard Prophet 21 help. 16. Click Next to move to the next step. 17. Enter the SQL server name and port you will use. Note: This screen only appears if you purchased the CPA\Datawarehouse product. 15. Click Next to review a summary of the setup selections. - 31 -
Configuring the Middleware Framework 14. Click Run Setup to install and configure files. If any one of the sections fails the install will stop. 15. Your Middleware configuration settings are now saved. If you have not already done so, you can close the Prophet 21 Middleware Setup program. - 32 -
Configuring the Middleware Framework 7 Updating the Middleware You must update the middleware every time you update the version of Prophet 21. Updating uses the same process as installing that is described in the previous chapters, however when updating you do not need to change any of the settings unless your environment has changed. That information will be in place and you can skip all the steps that ask you to enter those values. - 33 -
Configuring the Middleware Framework 8 Program Menu Items Middleare creates three menu items: 1. Configuration 2. Code Examples Application 3. Source Code for the Code Examples - 34 -
Configuration Configuration If you want to make a change to an instance of the Prophet 21 Middleware, find the configuration wizard here: Programs > Epicor Software > Epicor Prophet 21 Middleware. Depending if you are single instance or multiple instances the location may vary. Single Instance All menu options for a single instance configuration appear in the same folder. Multiple Instances If you use multiple instances, the menu options are grouped in folders named after each instance. - 35 -
Code Examples Application Code Examples Application The Middleware installation installs an application for testing the API against a database. When the application opens you ll need to specify a URL, Port, User and Password to connect. Note: When using the ERP Credentials option, you must use the admin account name and password. Once connected, you can run the tests listed, such as Get and Update. - 36 -
Code Examples Application Get - 37 -
Code Examples Application Update - 38 -
Source Code for the Code Examples Source Code for the Code Examples Command Line Process of the Installation You can run the installation from the command line with the following: Epicor.P21.Middleware.XXXX.exe /silent /instance<instance Name> Example: Instance Name = Live Epicor.P21.Middleware.Install.12.15.XXXX.exe /silent /Instance Live Shows Progress Bar during installation. Or Epicor.P21.Middleware,Install.12.15.XXXX.exe /verysilent /Instance Live Does Not show any progress bar during installation. - 39 -