Installing AX Server with PostgreSQL

Transcription

1 Installing AX Server with PstgreSQL Versin: 6.5 Published: Friday, September 1, 2017 ACL Services Ltd. 2017

2

3 Table f cntents Table f cntents Table f cntents 3 Intrductin 7 Intended audience 7 Pre-installatin tasks 9 Gathering installatin resurces 10 ACL Supprt Services 10 Primary ACL cntact 10 Database administratr 10 IT staff 11 AX Server prts 12 Checking prts in use 12 Prts required by the AX Server 12 Firewall cnfiguratin 14 Dwnlad the Analytics Exchange installers 15 Available installers 15 Dwnlad steps 15 Installatin 17 Install AX Server fr PstgreSQL 18 Install PstgreSQL 18 Install AX Server 21 Pst-installatin tasks 27 AX Server tasks 27 AX Client tasks 27 Verify that AX Server is running 28 Check the Analytics Exchange Service lg 28 Check the AX Server services 28 Checking the AX Server applicatins 28 Activate AX Server 30 Renewing a subscriptin? 30 Page 3 f 85

4 Table f cntents Online activatin 30 Offline activatin 30 Add an AX Server administratr 32 Cnfigure the Archive and Restre data directry 33 Verifying client applicatin cnnectins 34 Prerequisites 34 Applicatin cnnectin checks 34 Cnfiguring Pythn fr use with AX Server 36 Hw it wrks 36 Install Pythn versin 3.5.x (32-bit) 36 Set the PYTHONPATH envirnment variable 36 Installing AX Engine Nde (ptinal) 39 Install AX Engine Nde fr PstgreSQL 40 Install AX Engine Nde 40 Pstrequisites 43 Cnfiguring a shared data flder 44 Using shared data flders 44 Cnfigure a shared flder n Windws Cnfiguring AX Engine Ndes 45 Hw it wrks 45 Setting up AX Engine Ndes 45 Cnfiguring AX Engine Ndes 46 Security certificates 49 Hw it wrks 49 Using self-signed certificates fr AX Server 49 AX Engine Nde certificates 50 PstgreSQL cnnectins 50 ACL Cnnectr fr Analytics Exchange cnnectins 51 Installing security certificates fr AX Server 52 Tls and prerequisite knwledge 52 Backup the TmEE applicatin server cnfiguratin befre yu start 52 Server-side prcess 52 Page 4 f 85

5 Table f cntents Client-side prcess 55 Installing security certificates fr the ACL Cnnectr fr Analytics Exchange 56 Befre yu begin 56 Generating an SSL certificate fr self-signing 56 Generating an SSL certificate with a Certificate Authrity (CA) 57 Distributing the SSL certificates 59 Appendix 61 AX Server requirements 62 Hardware 62 Sftware 62 Autmatically installed prerequisites 64 Prerequisites included in Windws server 65 Database server 65 AX Engine Nde requirements 67 Hardware 67 Sftware 67 Autmatically installed prerequisites 69 Prerequisites included in Windws server 70 Service accunt cnfiguratin 71 Service names 71 Analytics Exchange Service 71 Analytics Exchange Cnnectr 72 Analytics Exchange Database 72 Analytics Exchange authenticatin 74 Authenticatin types 74 Chsing an authenticatin methd 74 Assigning rights fr the AX Cnnectr service 75 Assign read and write access t the AX Cnnectr installatin flder 75 Assign full cntrl rights t the AX Cnnectr executable (aclse.exe) 75 Allw lg n lcally rights 75 Cnfiguring Integrated Windws Authenticatin 77 Hw it wrks 77 Page 5 f 85

6 Table f cntents Create an SPN accunt 77 Map the authenticatin service t the SPN accunt 78 Register an SPN fr the AX Cnnectr service 78 Test the SPN accunt mapping 79 Enable Integrated Windws Authenticatin frm Internet Explrer 80 aclauditexchange.xml 81 File settings 81 Page 6 f 85

7 Intrductin Intrductin This guide is designed t walk yu thrugh the prcess f installing AX Server with a PstgreSQL database server. The cntents f this guide are limited t installatin and initial setup. Fr additinal infrmatin abut AX Server maintenance and using Analytics Exchange, visit the nline ACL Help Dcs. Intended audience This guide is written fr AX Server administratrs wh are respnsible fr the installatin and setup f Analytics Exchange fr their rganizatins. Page 7 f 85

8

9 Pre-installatin tasks Pre-installatin tasks Page 9 f 85

10 Pre-installatin tasks Gathering installatin resurces Befre yu begin installing r upgrading AX Server, identify the key cntacts yu need t prvide assistance and infrmatin fr the installatin prcess. ACL Supprt Services Cntact ACL Supprt Services if yu encunter prblems that yu cannt slve during the installatin r upgrade. Befre yu cntact ACL Supprt, ensure that yu have the fllwing infrmatin: The specific versin f AX Server that yu are installing r upgrading Details abut the database (PstgreSQL r Oracle) that yu are using with AX Server Any errr r warning messages that yu are encuntering Yu can cntact ACL Supprt Services in a number f different ways: submitting a supprt ticket nline (preferred methd) live chat (supprt@acl.cm) telephne Primary ACL cntact T dwnlad the AX Server installatin package frm Launchpad, yu must have a valid Launchpad accunt. If yu are the primary cntact at yur rganizatin, yu shuld have received a welcme frm ACL with instructins fr signing in t yur accunt. If yu have nt received the r need further assistance, cntact ACL Supprt Services. If yu are nt the primary cntact, yu shuld have received instructins by when the primary cntact added yu t Launchpad. If have nt received instructins, cntact yur rganizatin s primary cntact r ACL accunt administratr. Database administratr If yur rganizatin has a database administratr, he r she will have imprtant infrmatin yu require t install and cnfigure AX Server. Page 10 f 85

11 Pre-installatin tasks IT staff If yur rganizatin has IT staff wh administer services such as netwrk access, file strage, and security plicies, they may have infrmatin yu need t cmplete the installatin. They may als need t cmplete tasks such as creating Active Directry user accunts and mdifying firewall rules. Page 11 f 85

12 Pre-installatin tasks AX Server prts Fr the Analytics Exchange Service t start successfully n the AX Server server r AX Engine Nde, yu must ensure that the prts required by the TmEE applicatin server are nt being used by ther services r applicatins. Checking prts in use Frm a cmmand prmpt, use the NETSTAT cmmand t display in-use prts: NETSTAT -a If required prts are being used by anther service, yu must d ne f the fllwing: recnfigure the service t use a different prt temprarily disable the service in Windws Services while yu install AX Server If necessary, yu can mdify sme f the prts used by AX Server after the installatin prcess is cmplete. If yu are installing AX Server r AX Engine Nde fr the first time n a server, yu shuld verify that the prts required by the TmEE applicatin server are nt in use befre yu run the installer. Prts required by the AX Server AX Server and AX Engine Nde are installed with the default prt settings used by the Analytics Exchange Service. Prt Cmpnent Encryptin Descriptin 8009 Tmcat Cnnectr AJP Nn-SSL Prt used t cnnect t the TmEE applicatin server. This is a unidirectinal prt. It is used fr internally by AX Server and des nt need t be pened fr utside cmmunicatin. 80 Tmcat Cnnectr HTTP Nn-SSL Prt used fr unencrypted HTTP cmmunicatin with the server. This is a unidirectinal prt. It shuld be pened fr utside cmmunicatin n AX Server and AX Engine Nde. 443 Tmcat Cnnectr HTTPS SSL Prt used fr encrypted HTTP (HTTPS) cmmunicatin with the server. This is a bidirectinal prt. It must be pened n AX Server fr cm- Page 12 f 85

13 Pre-installatin tasks Prt Cmpnent Encryptin Descriptin municatin with AX Client. If yu are upgrading an earlier versin f AX Server, the default prt is PstgreSQL Supprted Yu can specify a different prt that is nt in use in the AX Server installer. If yu are cnfiguring a dual-server installatin, yu must ensure that the PstgreSQL and AX Server and AX Engine Nde can cmmunicate n this prt AX Cnnectr TwFish 128 bit If this prt is in use, yu can specify a different prt that is nt in use in the AX Server installer. This service is used primarily t access AX Server tables that have been exprted t ACL Analytics prjects. It must be pened n AX Server fr inbund cmmunicatin AX Engine Nde Nn-SSL Used t cnnect AX Engine Nde t the master AX Server. If the AX Engine Nde and AX Server are cmmunicating acrss a firewall, yu must pen this prt Oracle database Nn-SSL Prt used fr unencrypted Oracle database cmmunicatin. It must be pened n AX Server and AX Engine Nde fr cmmunicatin with the Oracle database. Yur IT team will stipulate which prt is required when Oracle is used as the AX Server database server. The prt can be changed after the installatin is cmpleted, if necessary Oracle database SSL Prt used fr encrypted Oracle database cmmunicatin. It must be pened n AX Server and AX Engine Nde fr cmmunicatin with the Oracle database if yu are encrypting the cnnectin. Yur IT team will stipulate which prt is required when Oracle is used as the AX Server database server. The prt can be changed after the installatin is cmpleted, if necessary ACL Cnnectr fr Analytics Exchange SSL Prt used fr establishing an ODBC cnnectin t analytic results. This prt is nly required if yu install the ptinal ACL Cnnectr fr Analytics Exchange service. It must be pened fr inbund cmmunicatin n AX Server. Page 13 f 85

14 Pre-installatin tasks Firewall cnfiguratin T cnnect t AX Server frm utside yur netwrk firewall, yu must allw inbund cnnectins n the fllwing prts: Prt Cmpnent Descriptin 443 Tmcat Cnnectr HTTPS AX Cnnectr 4201 AX Engine Nde Used t enable HTTPS cnnectins t the web server fr the AX Web Client and AX Server Cnfiguratin web applicatins, and fr secure file transfers t and frm AX Server. The default value fr servers upgraded frm versins prir t is Used t enable access t AX Server tables frm client cmputers thrugh ACL Analytics. Used t cnnect AX Engine Nde t the master AX Server. If the AX Engine Nde and AX Server are cmmunicating acrss a firewall, yu must pen this prt. Each client cmputer that cnnects t AX Server must als have the crrespnding prts pen fr utbund cmmunicatin. Page 14 f 85

15 Pre-installatin tasks Dwnlad the Analytics Exchange installers Dwnlad the installers frm Launchpad s yu can install Analytics Exchange. Yu must be able t sign in t an Launchpad accunt ( in rder t dwnlad Analytics Exchange installers, and activate AX Server. Available installers Installers fr the fllwing Analytics Exchange applicatins are available n Launchpad: AX Server (cntains installers fr bth AX Server and the PstgreSQL) AX Engine Nde ACL Analytics cmpatibility upgrade fr AX Server (if currently applicable) AX Client Direct Link Dwnlad steps The installer dwnlad page prvides the latest versin f Analytics Exchange. If yu require an installer fr a previus versin, yu must cntact ACL Supprt Services fr a cpy f the installer fr that versin 1. Sign in t Launchpad ( and click Analytics Exchange. An with sign in instructins is sent frm ntificatins@aclgrc.cm t yur cmpany's ACL accunt administratr. If yu are unable t sign in t yur Launchpad accunt, cntact yur cmpany s ACL accunt administratr r ACL Supprt Services fr assistance. 2. Frm the Select sftware package t dwnlad list, select the installer yu want t dwnlad. Ensure that yu dwnlad the crrect editin (nn-unicde r Unicde) as all installed applicatins must use the same editin. 3. Click Dwnlad <Versin> and save the installer t the cmputer that yu plan t install the applicatin n. Page 15 f 85

16

17 Installatin Installatin Page 17 f 85

18 Installatin Install AX Server fr PstgreSQL Install AX Server with PstgreSQL n the same physical machine. Install PstgreSQL Cautin Yu must install the KB Windws Updates befre starting yur Analytics Exchange installatin n Windws Server 2012 R2. If yu d nt install this update, yur Analytics Exchange installatin cannt succeed. Run the installer and select yur database cnfiguratin 1. Duble-click the installatin package and if a security warning dialg bx appears, verify the infrmatin listed and click Yes. 2. Select the setup language and click OK. 3. In the Setup Extractin Lcatin page, specify the flder where the installatin files will be extracted, and click Install. Tip Click Brwse t select a flder r accept the default lcatin: C:\Prgram Files (x86)\acl Sftware\Installers\ACLAX<versin>_Server_<editin>. 4. Click Yes in the dialg bx with the message abut the database engine. 5. In the Analytics Exchange Server Setup Optins page, select PstgreSQL and click Install. 6. T run the PstgreSQL setup wizard, click Yes. 7. If yu are prmpted t install prerequisites, click Install and wait while the prerequisites are installed. Fllw any n-screen instructins t cmplete the prerequisite setup. Cnfigure the database cnnectin and security 1. In the Welcme page, click Next and in the License Agreement page, select I accept the terms in the license agreement and click Next. Page 18 f 85

19 Installatin 2. In the Destinatin Flder page, accept the default PstgreSQL install lcatin r click Change t mdify the lcatin, and click Next. If yu mdify the installatin lcatin, the path yu specify must nt include any spaces. 3. In the Cnfigure yur Analytics Exchange PstgreSQL database server page select New Installatin and click Next. The PstgreSQL database server is installed and during the subsequent AX Server installatin prcess, a new Analytics Exchange database is created. 4. In the Service cnfiguratin page, enter the fllwing infrmatin t cnfigure the PstgreSQL database service and then click Next: Field Descriptin The name f the Windws user accunt that will run the service. Accunt name Keep the default accunt name pstgres unless yu have a reasn fr changing it. If the accunt des nt already exist, it will be created as a lcal user accunt. Yu cannt use accunts that belng t the Administratrs grup n the server. If yu use an existing accunt, the required file system permissins and the Lg n as a service right are assigned t the accunt. The name f the Active Directry dmain the user accunt belngs t. Accunt dmain If yu are using a lcal user accunt, keep the default value f the cmputer name. The passwrd fr the user accunt. Accunt passwrd Verify passwrd If the user accunt already exists, yu must enter the crrect passwrd. If the installer is creating a new accunt, enter the passwrd yu want t use. The passwrd must meet any passwrd cmplexity requirements that are enfrced by the Windws perating system. Additinally, the passwrd must nt include backslashes (\) r apstrphes ( ). Enter the passwrd again t verify it. 5. If the user accunt des nt exist, click Yes t create the accunt. 6. In the Database cnfiguratin page, enter the fllwing infrmatin and then click Next: Field Prt number Superuser name Passwrd Descriptin The prt number used fr cmmunicatins t and frm the PstgreSQL. The default prt is The name f the PstgreSQL Superuser accunt. The default value is pstgres and it cannt be changed. The passwrd fr the PstgreSQL Superuser accunt. Yur passwrd must nt include backslashes (\) r apstrphes ( ). Page 19 f 85

20 Installatin Field Descriptin Fr security reasns, d nt use the same passwrd that yu used fr the Windws user accunt that runs the PstgreSQL database service. Passwrd (again) Enter the passwrd again t cnfirm it. Make a nte f the PstgreSQL Superuser accunt name and passwrd. Yu need t enter them when yu create the Analytics Exchange database during the AX Server prtin f the installatin. Fr infrmatin abut cnfiguring service accunts, see "Service accunt cnfiguratin" n page In the SSL certificate infrmatin page, enter the fllwing infrmatin t create a self-signed security certificate t secure HTTPS cnnectins between the PstgreSQL and AX Server (and AX Exceptin if it is installed) and then click Next: Field Server name Department r divisin name Organizatin Name City Name State/Prvince Name Cuntry cde Passwrd Verify passwrd Descriptin The hstname f the database server. Fr example: ax.acl.cm. The divisin r business unit that the certificate is being issued fr. Fr example: Develpment. The name f yur cmpany r rganizatin. Fr example: ACL Services Ltd.. The city r lcality where yur cmpany r rganizatin is lcated. Fr example: Vancuver. The state r prvince where yur cmpany r rganizatin is lcated. Fr example: BC. The tw-character cuntry cde fr the cuntry where yur cmpany r rganizatin is lcated. Fr example: CA. Enter a passwrd f at least 6 characters. Enter the same passwrd again. Fr infrmatin abut hw this certificate is used, and fr cnfiguratin ptins, see "Security certificates" n page Click Install and when the installatin is cmplete, click Finish. The AX Server installatin prcess autmatically starts when the PstgreSQL installatin is cmplete. Page 20 f 85

21 Installatin Install AX Server Cnfigure yur Analytics Exchange services 1. If yu are prmpted t install prerequisites, click Install and wait while the prerequisites are installed. Fllw any n-screen instructins t cmplete the prerequisite setup. Yu may be required t restart yur cmputer after installing prerequisites. If yu d need t restart the cmputer, cntinue the installatin by duble-clicking the installer then and selecting the apprpriate language, installatin destinatin, and database server. Yu may be prmpted t accept the terms and cnditins fr the.net Framewrk when installing prerequisites. In this case, the terms and cnditins dialg bx may appear hidden behind the Analytics Exchange installer dialg bx. When installing the.net Framewrk, ensure that the installer is nt waiting fr yur input. 2. In the Welcme page, click Next and in the License Agreement page, select I accept the terms in the license agreement and click Next. 3. In the Destinatin Flders and Settings page, specify where the AX Server applicatin files will be installed and the lcatin where AX Server data will be stred. If necessary, click Change t mdify either, r bth, f the default lcatins. The paths yu specify must nt include any spaces, and the lcatin yu specify fr AX Server data must have sufficient disk space available. If yu want t stre AX Server data n a dedicated file server r ther netwrk lcatin, yu need t cnfigure the shared flder after yu cmplete the installatin. The shared flder cannt be specified in the AX Server installer. 4. In the Analytics Exchange Cnnectr prt number panel, enter the prt number fr the AX Cnnectr t use, r accept the default value f The AX Cnnectr service is used primarily t access ACL tables n AX Server frm ACL Analytics. 5. In the Analytics Exchange Tmcat Service Accunt panel, d the fllwing: a. Enter the dmain and username fr the accunt in the frmat dmain\username, r click Brwse t lcate the required dmain and username. If yu brwse fr the accunt name, yu must enter r select the dmain r server name first in the Brwse fr a User Accunt dialg bx in rder fr the installer t present the apprpriate list f available user accunts. Page 21 f 85

22 Installatin Using a lcal user accunt t run the TmEE service is nt supprted. These accunts d nt have the apprpriate privileges t run sme ACL cmmands. b. Enter the Passwrd fr the accunt. c. Click Next. d. If yu are prmpted t grant the Lg n as a service right t the Tmcat service accunt, click Yes and then OK. Fr infrmatin n the ptins fr cnfiguring service accunts, see "Service accunt cnfiguratin" n page 71. Cnfigure yur database cnnectin settings 1. In the Cnfigure yur Analytics Exchange database page, ensure that PstgreSQL is selected, and d ne f the fllwing: If yu are installing AX Server and PstgreSQL n the same physical server, deselect Encrypt database cmmunicatins. If yu are installing AX Server and PstgreSQL n separate physical servers, select Encrypt database cmmunicatins t encrypt the cnnectin. Tip Encryptin slws perfrmance smewhat, s yu shuld enable it nly if data is being transferred between the database server and the applicatin server ver an unsecure netwrk. 2. In the Analytics Exchange database cnnectin settings page, enter the fllwing infrmatin t cnfigure the cnnectin string: Field Descriptin The IP address r server name f the server where the database server is lcated. Database Server If yu are installing AX Server n the same physical server as PstgreSQL, keep the default value f lcalhst unless yu have a reasn t change it. Prt The prt t use t cnnect t the PstgreSQL database. The default prt is Superuser Passwrd The name f the PstgreSQL Superuser accunt. Leave the default value f pstgres unless yu have a reasn t change it. The passwrd fr the Super user accunt. 3. In the New PstgreSQL user fr Analytics Exchange database panel, enter the fllwing infrmatin and then click Next: Username: The name f the PstgreSQL database user accunt t use t access the Analytics Exchange database. The installer creates this user accunt when it creates the database. Passwrd: The passwrd fr the PstgreSQL database user accunt. Page 22 f 85

23 Installatin Passwrd (again): Enter the passwrd fr the PstgreSQL database user accunt again t cnfirm it. Cnfigure security and authenticatin 1. In the Micrsft Active Directry Cnnectin Details page, verify that the value in the Default Dmain text bx is crrect, r enter the crrect value, and click Next. The default dmain value is the dmain end users are authenticated against if they d nt specify a dmain when they lg in using frm-based authenticatin. Fr example, if an end user enters jsmith as their username, and the default dmain is ACL, it is equivalent t entering acl\jsmith. 2. In the Analytics Exchange Authenticatin page, select the apprpriate authenticatin methd: Frm Based Authenticatin: Select this ptin if yu want users t be prmpted t enter their username and passwrd each time they start a new sessin with Analytics Exchange. A sessin is created when a new web brwser windw is pened, r when AX Client is started. Integrated Windws Authenticatin: Select this ptin if yu want users t be silently authenticated by Analytics Exchange applicatins based n the user accunt used t lg in t Windws. User accunts that belng t the cnfigured Active Directry dmain will nt need t enter their username and passwrd infrmatin when they access Analytics Exchange applicatins. Fr mre infrmatin abut the authenticatin ptins and the required cnfiguratin, see "Analytics Exchange authenticatin" n page Specify the AX Server authenticatin cnfiguratin details by ding ne f the fllwing and then click Next: If yu selected Frm Based Authenticatin, specify the hstname f the server where AX Server is installed. Fr example: AX.ACL.COM. If yu selected Integrated Windws Authenticatin, enter the fllwing infrmatin: Analytics Exchange Server Hstname: Specify the hstname f the server where AX Server is installed. Fr example: AX.ACL.COM Active Directry Dmain Specify the Active Directry Dmain t use t authenticate users Kerbers Dmain Cntrller IP Address The IP address where yur rganizatin s Active Directry Dmain Cntrller is lcated Kerbers Service Passwrd The passwrd fr the Service Principal Name (SPN) accunt created in Active Directry 4. If yu have an existing SSL security certificate, d the fllwing in the SSL certificate infrmatin page: a. Select Use existing keystre file and brwse t the keystre file n yur cmputer. b. Enter the existing Keystre passwrd. Page 23 f 85

24 Installatin 5. In the SSL certificate infrmatin page, enter the fllwing infrmatin and then click Next: Field Server name Department r divisin name Organizatin Name City Name State/Prvince Name Cuntry cde Descriptin The hstname f the database server. Fr example: ax.acl.cm. The divisin r business unit that the certificate is being issued fr. Fr example: Develpment. The name f yur cmpany r rganizatin. Fr example: ACL Services Ltd.. The city r lcality where yur cmpany r rganizatin is lcated. Fr example: Vancuver. The state r prvince where yur cmpany r rganizatin is lcated. Fr example: BC. The tw-character cuntry cde fr the cuntry where yur cmpany r rganizatin is lcated. Fr example: CA. Enter a passwrd f at least 6 characters. Keystre passwrd Private key passwrd If yu are using an existing keystre file, this instance f the Keystre passwrd text bx is disabled. Enter the same passwrd again. The Keystre passwrd and the Private key passwrd must be identical. Fr infrmatin abut hw this certificate is used, and fr cnfiguratin ptins, see "Security certificates" n page In the Enter Tmcat cnsle username and passwrd page, enter the fllwing infrmatin and then click Next: Username: Enter the username yu want t use t access and administer the Tmcat Web Applicatin Manager and the AX Server Cnfiguratin web applicatin Passwrd: Enter a passwrd fr the username Cnfirm passwrd: Enter the passwrd again t cnfirm it Finish the installatin 1. Click Install. Befre the installatin prcess cmpletes yu are required t wait fr abut a minute while the TmEE applicatin server becmes fully functinal. The cmmand windw may appear intermittently during this perid. D nt cancel the installatin. 2. When the installatin prcess is cmplete, click Finish t exit the installer. Page 24 f 85

25 Installatin The AX Server Cnfiguratin web applicatin pens in the default web brwser after the installer finishes. Yu must cmplete pst-installatin tasks in the web applicatin in rder fr AX Server t be fully functinal. Fr mre infrmatin, see "Pst-installatin tasks" n page 27. If the AX Server Cnfiguratin web applicatin displays an errr in the web brwser, wait fr 2-3 minutes befre relading the page. Depending n yur server hardware, the required services may take a few minutes t be fully functinal. If yu clse the AX Server Cnfiguratin web applicatin befre cmpleting all the pst-installatin tasks, yu can access the web applicatin again in a web brwser. The default lcatin is where <servername> is the hstname r IP address f yur AX Server. Fr example: Page 25 f 85

26

27 Pst-installatin tasks Pst-installatin tasks Cmplete the fllwing tasks t finalize yur AX Server installatin. Depending n yur AX Server cnfiguratin, sme f these tasks may be ptinal. If yu have cmpnents n multiple physical servers, yu may need t cmplete the tasks n each machine. AX Server tasks 1. Verify that AX Server is running. Fr mre infrmatin, see "Verify that AX Server is running" n the next page. 2. Activate AX Server. Fr mre infrmatin, see "Activate AX Server" n page Add an AX Server administratr. Fr mre infrmatin, see "Add an AX Server administratr" n page Cnfigure the Archive and Restre data directry. Fr mre infrmatin, see "Cnfigure the Archive and Restre data directry" n page Optinal. Install and cnfigure Pythn n AX Server and any instances f AX Engine Nde if yu intend t use Pythn integratin in Analytic scripts. Fr mre infrmatin, see "Cnfiguring Pythn fr use with AX Server" n page 36. AX Client tasks 1. Verify client applicatin cnnectins. Fr mre infrmatin, see "Verifying client applicatin cnnectins" n page Optinal. Frm the AX Server machine, cnfigure the applicatin timeut setting fr AX Client. By default, the applicatin times ut after sitting idle fr 30 minutes. Yu can change this maximum idle time setting in the aclauditexchange.xml cnfiguratin file. Fr mre infrmatin, see "aclauditexchange.xml" n page 81. Page 27 f 85

28 Pst-installatin tasks Verify that AX Server is running Verify AX Server is running by checking the service lg, services, and the Tmcat Web Applicatin Manager. Check the Analytics Exchange Service lg T check that the Analytics Exchange Service is running, in the TmCat/lgs sub-directry f AX Server, pen the TmEE.date.lg file and review the lg entries. A new lg file is created each time the service is started/restarted r when the file exceeds the maximum file size. Check the AX Server services The status f each AX Server Windws service shuld be Started r Running. If yu have installed AX Server cmpnents n mre than ne server, make sure t check the services n all servers. 1. On t the server where the services are running, navigate t the Windws Cntrl Panel, select Administrative Tls, and then pen Services. 2. In the Services windw, check that the fllwing services are listed as Started r Running in the Status clumn: Analytics Exchange Service: runs n AX Server and each instance f AX Engine Nde AX Cnnectr: runs nly n AX Server Analytics Exchange Database <versin number>: runs n the server where the PstgreSQL is installed This service may run n the same server as AX Server, r n a separate server. The service is present nly if PstgreSQL is the database server fr AX Server If any f the services have nt started, yu can try t start them by right-clicking the service and selecting Start. If the service still des nt start, check the lg file t determine the cause f the prblem r cntact ACL Supprt Services. Checking the AX Server applicatins Check the deplyment status f the AX Server applicatins frm the Tmcat Web Applicatin Manager. 1. Frm a web brwser, navigate t and lg in t the Tmcat Web Applicatin Manager. Page 28 f 85

29 Pst-installatin tasks Replace server_name with the hstname r IP address f the server hsting AX Server r the AX Engine Nde instance. Yur Tmcat Web Applicatin Manager credentials are specified during the AX Server installatin. If yu cannt remember yur credentials, reset them. 2. Cnfirm that the fllwing applicatins display the Running status as true n AX Server: Analytics Exchange (AX) Server <versin number> AX Webclient <versin number> AX System Admin <versin number> AX Cre Server <versin number> AX Central Authenticatin System (CAS) <versin number> AX Gateway Mapper <versin number> AX Light Client <versin number> Tmcat Hst Manager Applicatin Tmcat Manager Applicatin AX Cre REST Interface <versin number> Apache TmEE If any f the applicatins have nt started, in the Cmmands clumn, click Start. 3. Exit the Tmcat Web Applicatin Manager. Page 29 f 85

30 Pst-installatin tasks Activate AX Server Yu can activate yur AX Server nline using the AX Server Cnfiguratin r ffline using Launchpad. Yu must have a valid Launchpad accunt with the apprpriate permissins t activate AX Server. If yu d nt have an Launchpad accunt, cntact yur ACL accunt administratr. Renewing a subscriptin? If yu are renewing an expired subscriptin, yu must deactivate and then reactivate yur instance f AX Server t cmplete the renewal prcess. Fr infrmatin abut deactivating the server, see Deactivate AX Server. Online activatin 1. Sign in t the AX Server Cnfiguratin web applicatin ( and lcate the Activatin panel. 2. Frm the Server Type list, select ne f the fllwing: Prductin: the primary prductin server Nn-Prductin: the server used fr nn-prductin purpses such as testing and staging Disaster Recvery: the server designated fr disaster recvery r failver 3. In Activatin, enter yur Launchpad credentials and click Select Org. 4. Frm the Organizatins list, select the rganizatin the server belngs t and click Activate Server. Result: After the identificatin file imprts, The server has been activated displays. Offline activatin 1. Sign in t the AX Server Cnfiguratin ( web applicatin and lcate the Activatin panel. 2. Frm the Server Type list, select ne f the fllwing: Prductin: the primary prductin server Nn-Prductin: the server used fr nn-prductin purpses such as testing and staging Disaster Recvery: the server designated fr disaster recvery r failver 3. In Offline Activatin, click Generate and save the machine identifier file AXOfflineActivatin.mif n yur lcal wrkstatin. Page 30 f 85

31 Pst-installatin tasks Yur lcal wrkstatin must have an Internet cnnectin t access Launchpad and cmplete the rest f the activatin. 4. Sign in t Launchpad ( and select yur rganizatin. 5. Select Optins > Activatins and n the left-hand side, click Offline Activatin. 6. Uplad yur activatin file: a. Click Chse File, brwse t yur server machine identifier file AXOfflineActivatin.mif and click Open. b. Frm the Applicatin drp-dwn list, select the AX Server installatin type. c. Frm the User drp-dwn list, select yur name and then click Uplad. Result: Once the machine identifier file uplads, the machine name f the server appears in the Activatins list. 7. Next t the name f the activated server, click Dwnlad Activatin File and save the activatin file analytics_exchange_server.af n yur lcal wrkstatin. 8. Frm the AX Server Cnfiguratin web applicatin, in the Offline Activatin sectin, brwse t the activatin file that yu dwnladed frm Launchpad and click Imprt. Result: After the identificatin file imprts, The server has been activated displays. Page 31 f 85

32 Pst-installatin tasks Add an AX Server administratr Use the AX Server Cnfiguratin web applicatin t add an administrative user. The user is granted the Administratr rle. Yu must add at least ne administrative accunt after installing AX Server t use AX Client. Once yu add the first user, yu can use AX Client t add mre users. 1. In a web brwser, navigate t and lg in t the AX Server Cnfiguratin web applicatin. Use the same credentials that yu use t lg in t the Tmcat Web Applicatin Manager. 2. Lcate the Add AX administratr panel, and enter the name f the Windws user accunt t add: If the user accunt belngs t the default Active Directry dmain fr yur Analytics Exchange implementatin, yu can enter the user name withut specifying the dmain. The default dmain fr AX Server is specified in the Settings sectin f the Server panel. If the user accunt des nt belng t the default Active Directry dmain, yu need t specify the dmain and the user name using the fllwing frmat: Dmain\username If the user accunt is a lcal Windws user accunt n the server where AX Server is installed, yu need t specify the cmputer name and the user name using the fllwing frmat: CmputerName\UserName 3. Click Add Administratr. Page 32 f 85

33 Pst-installatin tasks Cnfigure the Archive and Restre data directry Cnfigure the Archive and Restre data directry t make the Archive and Restre cmmands available t end-users with applicatin Administratr rights in AX Client. If the directry is nt cnfigured, the Archive and Restre cmmands are disabled in AX Client. 1. In a web brwser, navigate t and lg in t the AX Server Cnfiguratin web applicatin. Use the same credentials that yu use t lg in t the Tmcat Web Applicatin Manager. 2. In the Server sectin, in the Archive and restre data directry field, enter the file path r UNC path t the directry where yu save archived cllectins. Yu must specify a flder that already exists. A UNC path is a shared flder that is specified using the fllwing frmat: \\<server_name>\<shared_flder>. The user accunt used t run the Analytics Exchange Service must have Full Permissins fr the flder yu cnfigure as the Archive and Restre data directry. Yu must manually assign the required security rights in Active Directry. The data directry can either be lcated lcally n AX Server, r n a remte file server r strage-area netwrk (SAN). Yu must ensure that the specified lcatin has enugh disk space allcated t stre yur archived cllectins based n the size f cllectins stred in AX Server, including analytic jb results, and yur rganizatin s archiving plicies. 3. T save yur changes, click Update at the bttm f the Server sectin. Page 33 f 85

34 Pst-installatin tasks Verifying client applicatin cnnectins Check that lcal and any remte users can cnnect t AX Server using AX Client, ACL Analytics, and AX Web Client after installing AX Server and any instances f AX Engine Nde. Prerequisites At the lcatins that users will cnnect frm: install AX Client install ACL Analytics Applicatin cnnectin checks Check Start AX Client and cnnect t AX Server. Details If yu are unable t lg in, cnfirm the fllwing settings: If the user accunt yu are lgging in with des nt belng t the default Active Directry dmain specified fr AX Server, yu must specify the dmain when yu lg in. Fr example: DmainName\Username The Server settings specified in the Optins dialg bx must match the settings required by AX Server. If a firewall is present n the client cmputer where AX Client is running, ensure that the required prts are pen fr utbund cmmunicatin. By default, the required prt is 443 (Tmcat Cnnectr HTTPS). Prt (AX Cnnectr) must als be pen if ACL Analytics is being used. Exprt a table frm AX Server that has a surce data file stred n AX Server. Launch the Help a. When yu select the table, check that the Data surce prperty specifies Data surce is managed by AX Server. b. In the Exprt dialg bx, make sure that Wrk with the exprted file(s) is selected, and Exprt data files alng with selected definitins is deselected (the default settings). c. If yu are able t pen the table in ACL Analytics after entering the server prfile passwrd, then AX Cnnectr is cnfigured crrectly. d. If yu are nt able t pen the server table, see "Assigning rights fr the AX Cnnectr service" n page 75 fr instructins n cmpleting the additinal security cnfiguratin that may be necessary. When yu imprt an ACL prject r an analytic int AX Server, and select Imprt surce data files (.fil files), any tables in the prject are cnverted int server tables and the assciated ACL data files (.fil) are cpied t AX Server. Server tables are accessed using AX Cnnectr. If HTTP requests frm the client cmputer are redirected t a prxy server, attempts t access the Page 34 f 85

35 Pst-installatin tasks Check system by selecting Help > Cntents. Details Help system may fail. Yu can specify the crrect IP address and prt fr the prxy server by adding the fllwing tw lines t the ACLAnalyticsExchange.ini file in the flder where AX Client is installed. The default lcatin is C:\Prgram Files\ACL Sftware\ACL Analytics Exchange Client. -Dhttp.prxyHst=<prxy_server_hstname_r_ip> -Dhttp.prxyPrt=<prxy_server_prt> Fr example: -Dhttp.prxyHst= Dhttp.prxyPrt=3128 Page 35 f 85

36 Pst-installatin tasks Cnfiguring Pythn fr use with AX Server T cnfigure Pythn t wrk with AX Server, yu must install the crrect versin f Pythn, add the Pythn executable t yur system PATH envirnment variable, and set the PYTHONPATH system envirnment variable n each machine that hsts an instance f AX Server r AX Engine Nde. Hw it wrks T run Pythn scripts, Analytics Exchange must be able t call the Pythn executable and find the scripts it is instructed t run. AX Server uses the PATH envirnment variable t lcate Pythn and the PYTHONPATH envirnment variable t lcate scripts. Install Pythn versin 3.5.x (32-bit) Yu must cmplete these steps n every machine that hsts an instance f AX Server r AX Engine Nde. 1. Frm the Pythn dwnlads page, dwnlad the latest versin f Pythn 3.5 t yur machine. 2. On yur machine, duble-click the installer. 3. In the installer, select Add Pythn versinnumber t PATH. 4. Click Install and fllw the n-screen instructins. 5. Rebt the machine befre running any Pythn scripts frm ACL. Set the PYTHONPATH envirnment variable Yu must cmplete these steps n every machine that hsts an instance f AX Server r AX Engine Nde. The user accunt that runs the Analytics Exchange Service must have permissin t access the flder(s) in yur PYTHONPATH envirnment variable. 1. In yur Windws perating system, create ne r mre flders t huse yur Pythn scripts. Example C:\pythn_scripts. 2. Frm yur Windws perating system, pen the System Prperties dialg bx and click Envirnment Variables. 3. In the System variables sectin, click New and enter the fllwing: Variable name PYTHONPATH Variable value enter the full path t the flder(s) yu created t huse the Pythn scripts Separate multiple flder paths with a semi-cln: C:\pythn_scripts;C:\dev;C:\tmp. Page 36 f 85

37 Pst-installatin tasks 4. T save the variable, click OK and then in the System Prperties dialg bx, click OK. Page 37 f 85

38

39 Installing AX Engine Nde (ptinal) Installing AX Engine Nde (ptinal) Page 39 f 85

40 Installing AX Engine Nde (ptinal) Install AX Engine Nde fr PstgreSQL Install AX Engine Nde t increase the analytic prcessing capability f Analytics Exchange. AX Engine Nde is hsted n a separate server frm AX Server. Install AX Engine Nde Cautin Yu must install the KB Windws Updates befre starting yur Analytics Exchange installatin n Windws Server 2012 R2. If yu d nt install this update, yur Analytics Exchange installatin cannt succeed. Run the installer and select yur database cnfiguratin 1. Duble-click the installatin package and if a security warning dialg bx appears, verify the infrmatin listed and click Yes. 2. Select the setup language and click OK. 3. In the Setup Extractin Lcatin page, specify the flder where the installatin files will be extracted, and click Install. Tip Click Brwse t select a flder r accept the default lcatin: C:\Prgram Files (x86)\acl Sftware\Installers\ACLAX<versin>_EngineNde_ <editin>. 4. In the Analytics Exchange Server Setup Optins page, select PstgreSQL and click Next. 5. If yu are prmpted t install prerequisites, click Install and wait while the prerequisites are installed. Fllw any n-screen instructins t cmplete the prerequisite setup. Cnfigure yur database service 1. In the Welcme page, click Next and in the License Agreement page, select I accept the terms in the license agreement and click Next. 2. In the Destinatin Flders page, specify where the AX Engine Nde applicatin files will be installed and the wrking directry fr analytic prcessing, and then click Next. If necessary, click Change t mdify either, r bth, f the default lcatins. The paths yu specify must nt include any spaces. 3. In the ACL Analytics Exchange server infrmatin page, enter the IP address f the server where AX Server is installed and click Next. Page 40 f 85

41 Installing AX Engine Nde (ptinal) 4. In the first Analytics Exchange Server database cnnectin settings page, select PstgreSQL frm the Database Platfrm ptins. 5. T encrypt the database cnnectin, select Encrypt database cmmunicatins and then click Next. T encrypt the cnnectin, yur database server must be cnfigured fr SSL cnnectins. Tip Encryptin slws perfrmance smewhat, s yu shuld enable it nly if data is being transferred between the database server and the applicatin server ver an unsecure netwrk. 6. In the secnd Analytics Exchange Server database cnnectin settings page, enter the fllwing infrmatin: Field Descriptin The IP address r server name f the server where the database server is lcated. Database Server If yu are installing AX Server n the same physical server as PstgreSQL, keep the default value f lcalhst unless yu have a reasn t change it. Prt The prt t use t cnnect t the PstgreSQL database. The default prt is Superuser Passwrd The name f the PstgreSQL Superuser accunt. Leave the default value f pstgres unless yu have a reasn t change it. The passwrd fr the Super user accunt. Cnfigure the applicatin service accunt and security 1. In the Analytics Exchange Tmcat Service Accunt panel, d the fllwing and click Next: a. Enter the dmain and username fr the accunt in the frmat dmain\username, r click Brwse t lcate the required dmain and username. If yu brwse fr the accunt name, yu must enter r select the dmain r server name first in the Brwse fr a User Accunt dialg bx in rder fr the installer t present the apprpriate list f available user accunts. Using a lcal user accunt t run the TmEE service is nt supprted. These accunts d nt have the apprpriate privileges t run sme ACL cmmands. b. Enter the Passwrd fr the accunt. c. Click Next. d. If yu are prmpted t grant the Lg n as a service right t the Tmcat service accunt, click Yes and then OK. Page 41 f 85

42 Installing AX Engine Nde (ptinal) Fr infrmatin n the ptins fr cnfiguring service accunts, see "Service accunt cnfiguratin" n page In the SSL certificate infrmatin page, enter the fllwing infrmatin t create a self-signed security certificate t secure HTTPS cnnectins t the AX Engine Nde and then click Next: Field Server name Department r divisin name Organizatin Name City Name State/Prvince Name Cuntry cde Descriptin The hstname f the database server. Fr example: ax.acl.cm. The divisin r business unit that the certificate is being issued fr. Fr example: Develpment. The name f yur cmpany r rganizatin. Fr example: ACL Services Ltd.. The city r lcality where yur cmpany r rganizatin is lcated. Fr example: Vancuver. The state r prvince where yur cmpany r rganizatin is lcated. Fr example: BC. The tw-character cuntry cde fr the cuntry where yur cmpany r rganizatin is lcated. Fr example: CA. Enter a passwrd f at least 6 characters. Keystre passwrd Private key passwrd If yu are using an existing keystre file, this instance f the Keystre passwrd text bx is disabled. Enter the same passwrd again. The Keystre passwrd and the Private key passwrd must be identical. Fr infrmatin abut hw this certificate is used, and fr cnfiguratin ptins, see "Security certificates" n page 49. Finish the installatin 1. Click Install. Befre the installatin prcess cmpletes yu are required t wait fr abut a minute while the TmEE applicatin server becmes fully functinal. The cmmand windw may appear intermittently during this perid. D nt cancel the installatin. 2. When the installatin prcess is cmplete, click Finish t exit the installer. Page 42 f 85

43 Installing AX Engine Nde (ptinal) Pstrequisites "Cnfiguring a shared data flder" n the next page "Cnfiguring AX Engine Ndes" n page 45 Page 43 f 85

44 Installing AX Engine Nde (ptinal) Cnfiguring a shared data flder T stre data files n a separate server frm AX Server r t supprt AX Engine Nde n ne r mre servers yu must prvide access t AX Server data files thrugh a shared flder. Using shared data flders There are tw cmmn use cases fr shared data flders: external data strage yu can stre the data files n a server where there is mre hard disk space available r n a netwrk file server AX Engine Nde installatins require a shared flder s that the analytic servers and AX Server can access data files. Shared flder lcatin The shared flder must be accessible thrugh a Windws UNC path with the fllwing frmat: \\CmputerName\SharedFlder and be lcated either in a shared Windws flder r a Strage Area Netwrk (SAN). Required flder permissins The Windws user accunt used t run the TmEE applicatin server service n the AX Server and each AX Engine Nde must have read and write permissins fr the flder. Any users that access AX Server tables using ACL Analytics must have read access permissins fr the flder. Cnfigure a shared flder n Windws In Windws Explrer, right-click the flder yu want t share and select Share. 2. In the File Sharing dialg bx, select the users r grups yu want t share the flder with. 3. Check the permissins assigned t each user r grup, and click the drp-dwn list beside each entry yu want t mdify the permissins fr and select the apprpriate permissins. 4. Click Share and then click Dne. Page 44 f 85

45 Installing AX Engine Nde (ptinal) Cnfiguring AX Engine Ndes Use ne r mre instances f AX Engine Nde t run analytics acrss multiple servers and increase prcessing pwer. Hw it wrks Increasing prcessing pwer By default, analytics are prcessed directly n AX Server. Althugh this wrks in mst cases, yu may require mre prcessing pwer when: yu want t run anlaytics requiring high prcessing pwer yu want t run a number f analytics in a shrt span f time T increase prcessing pwer, yu can cnfigure ne r mre instances f AX Engine Nde and run yur analytics n these separate servers. Balancing multiple ndes When a nde has space in its queue, it ntifies AX Server that it can prcess jbs and the server then assigns jbs t that nde. As a result, running multiple AX Engine Ndes that are allwed t handle several jbs simultaneusly can cause ne nde t handle multiple jbs while thers sit idle. T ensure jbs are balanced acrss ndes, cnfigure the maximum number f jbs each nde can prcess as 1 and schedule analytic jbs accrdingly. Setting up AX Engine Ndes Prerequisites Befre yu add and cnfigure an AX Engine Nde in the AX Server Cnfiguratin web applicatin, yu must: cnfigure yur system s that AX Server data files are stred in a shared flder which is accessible using a UNC path (e.g. \\server_name\shared_flder). Fr mre infrmatin, see "Cnfiguring a shared data flder" n the previus page physically install and cnfigure each instance f AX Engine Nde n a server Add an AX Engine Nde 1. Sign in t the AX Server Cnfiguratin web applicatin and lcate the Engine Ndes panel. Page 45 f 85

46 Installing AX Engine Nde (ptinal) 2. In the Add Engine Nde panel, enter the fllwing infrmatin: New Engine Nde IP address r cmputer name: the hstname r IP address f the server where the AX Engine Nde is installed Jbs (max): the maximum number f analytic jbs that the engine nde can prcess at ne time Jbs are queued until the number f cncurrently running jbs falls belw the maximum. 3. Click Add Engine Nde. 4. Click Update Engine Nde Settings. Result: The AX Engine Nde is used t prcess analytics. If it is the first AX Engine Nde, prcessing is transferred frm AX Server t the new nde. If yu added multiple AX Engine Ndes, scheduled jbs are distributed amng them. Cnfiguring AX Engine Ndes Frm the Engine Ndes panel f the AX Server Cnfiguratin web applicatin, yu can edit the cnfiguratin settings f any AX Engine Nde yu have added. When yu edit a value, click Update t save the change. Individual AX Engine Nde settings Enabled/disable an engine nde Change the Hstname r IP address Change the max jbs Remve an engine nde Glbal AX Engine Nde settings These settings apply t all instances f AX Engine Nde and all analytics that run n the server(s). Yu can cpy data files t each AX Engine Nde instance befre analytics are prcessed using the Cpy analytic data t engine nde setting: Yes: data files frm the analytic flder f AX Server are cpied t the analytic jb directry f the AX Engine Nde befre prcessing starts N: data files remain in the analytic flder f AX Engine Nde and are nt cpied t the jb directry f the AX Engine Nde befre prcessing starts Page 46 f 85

47 Installing AX Engine Nde (ptinal) Cpy data files Imprves perfrmance when data files are repeatedly accessed acrss the netwrk Imprves perfrmance when running multiple analytics simultaneusly r if a single analytic runs several cmmands n large data files D nt cpy data files Imprves perfrmance when a small number f analytics run simultaneusly Imprves perfrmance when the time t cpy data files utweighs the time yu can save by by writing yur analytics s that, whenever pssible, analytic cmmands are run lcally n the AX Engine Nde. Fr example: a. Write a cmmand t select nly the required recrds frm the table the script pens remtely. b. Use the EXTRACT cmmand with the LOCAL parameter specified t extract the recrds int a new table n the AX Engine Nde instance. c. Run any additinal cmmands n the lcal table. Page 47 f 85