		APPX Data Services - README.TXT
		
The APPX Data Services module is currently compatible with version 5.5.x and 6.2.x of the APPX runtime environment and is designed to provide an interface
between the APPX runtime environment and Web-based services such as; a Web server or a mobile application.

1) Prerequisites

	a) An installation of version 5.5.x or 6.2.x of the APPX runtime environment
	b) A dedicated APPX username/password setup in the APPX runtime environment for logins
	c) A dedicate APPX Login Manager instance, to login to the APPX runtime environment as an APPX user

	When the 5.5.x or 6.2.x version of the APPX runtime environment is installed, for the first time, you are given an option to install an APPX Login Manager instance for use 
	with the APPX Data Services module.  If you didn't exercise that option, you can manually create an instance of the APPX Login Manager by following the instruction below at 4).

2) Installing and removing the APPX Data Services Service

	Use the command line examples below, to install an APPX Data Services service instance.  The examples below apply to both Linux and Windows.
	These commands must be executed in the APPX Data Services script directory.  

	Install the required Node JS modules.
		npm install --loglevel=error

	Install the APPX Data Services service instance.
		Replace items in <> with values of your choice, for example:
		<webport> = 3000
		<portnumber> = 8161
		<appx username> = a user defined in APPX (not an OS user)
		<appx password> = the password of the user defined in APPX
		<configuration file name> = the name of the configuration file to be used installation
	
		The install service command:
			node servicectl.js install -p <webport> --appxhost=<hostname> --appxport=<portnumber> --appxuser=<appx username> --appxpass=<appx password>
				Example:
				node servicectl.js install -p 3000 --appxhost=myhost --appxport=8161 --appxuser=Test --appxpass=password
				
			node servicectl.js install --configfilename=<configuration file name>
				Example:
				node servicectl.js install --configfilename=default-3000.json.bak

		The remove service command:
			node servicectl.js remove --p=<webport>
				Example:
				node servicectl.js remove --p=3000
				
	After installation a configuration file will be created in the 'config' subdirectory of the APPX Data Services directory.
	That configuration file is a JSON formatted file and will be named default-xxxxx.json where xxxxx is the <webport> number specified on the during installation.
	The configuration file is where you can change the parameters that where specified during the installation.  
	Also, you can change other parameters that weren’t specified during installation such as whether to use SSL and the SSL certificate file and its key file.
	For example:
		To specify that SSL be used on the web interface set 
			"enablessl": true
		in the "AppConfig" section.
	
		To specify that SSL be used on the APPX login manager interface set 
			"enablessl": true
		in the "ProviderConfig" section.
	
		To sepcify the SSL certificate and key files for Windows set; 
			"systemcert": "C:\\Certs\\myhost.crt",
			"certificatepath": "C:\\Certs\\myhost.crt",
			"privatekeypath": "C:\\Certs\\myhost.key",
		and for Linux set;
			"systemcert": "/opt/certs/myhost.crt",
			"certificatepath": "/opt/certs/myhost.crt",
			"privatekeypath": "/opt/certs/myhost.key",
		in the "AppConfig" section.				

	After removal, the there will be a backup copy of the configuration file created in the APPX Data Services directory service with a .bak extension.
	This backup copy can be used for reinstallation of a APPX Data Services instance as shown earlier.

3) Creating a Persistent Authentication Token
	For faster logins you can create a persistent authentication token that can be used in place of the appxuser and appxpassword.
	To create that token for 5.5.x, run the script as shown below, after substituting <username> with the actual name of the user:
		node createPAT.js --username=<username>

	Please note, the tokens generated by the createPAT.js script are incompatible with Appx 6.2.x.
		
	To create that token for 6.2.x, run the 6.2.x appxLoginMgr, from the services directory as shown below, after substituting <name> with the actual name of the user
	and <password> with the actual password of the user: 
		appxLoginMgr.exe -token -name=<userName> -pw=<password>

	Please note, the tokens generated by the 6.2.x appxLoginMgr are incompatible with Appx 5.5.x.

	After creating the token, copy it into the APPX login manager 'tokens' directory.
	Then, in the configuration file, change the "ProviderConfig" section paramter as follows: "appxtoken": <token file name>
	Next, in the "ProviderConfig" section change the following: ""appxuser": "" and "appxpass": ""
	Finally, stop and then restart the APPX Data Services service

4) Manually installing a new APPX Login Manager Service Instance 

	Use the command line examples below, to manually create an APPX Login Manager Service instance for APPX Data Services.    
	These commands should be executed in the APPX login manager executable directory.  

		Replace items in <> with values of your choice, for example:
		<service name> = AppxDSLoginManager-8161
		<service display name> = AppxDSLoginManager-8161
		<portnumber> = 8161
		<full path to appx engine executable> = for Linux: /opt/appxserver/appx | for Windows: c:\appx\Appx.exe
		<path to the appx data directory> = for Linux: /opt/appxserver/data  | for Windows: c:\appx\data

	Linux:
	sudo ./appxLoginMgr -install -name=<service name> -displayName="<service display name>" -SockPort=<portnumber> -engine=<full path to appx engine executable> -AuthenticationMethod=Appx-User -ImpersonateGroup=NamedGroup\(appxgrp\) -ImpersonateUser=NamedUser\(appx\) -AppxProcessName=WEBSERVICES -AppxProcessType=SUBROUTINE -AppxApplication=0LA -AuthenticationMethod=Appx-User -ServiceType=data APPXPATH=<path to the appx data directory> APPX_KEYMAP=Windows
		Example:
		sudo ./appxLoginMgr -install -name=AppxDSLoginManager-8161 -displayName="AppxDSLoginManager-8161" -SockPort=8161 -engine=/opt/appxserver/appx -AuthenticationMethod=Appx-User -ImpersonateGroup=NamedGroup\(appxgrp\) -ImpersonateUser=NamedUser\(appx\) -AppxProcessName=WEBSERVICES -AppxProcessType=SUBROUTINE -AppxApplication=0LA -AuthenticationMethod=Appx-User -ServiceType=data APPXPATH=/opt/appxserver/data APPX_KEYMAP=Windows

	Windows:
	cmd /c "appxLoginMgr.exe -install -name=<service name> -displayName=<service display name> -SockPort=<portnumber> -engine=<full path to appx engine executable> -AppxApplication=0LA -AppxExecutable=c:\appx55\Appx.exe -AppxProcessName=WEBSERVICES -AppxProcessType=SUBROUTINE -AuthenticationMethod=Appx-User -ServiceType=data APPXPATH=<path to the appx data directory> APPX_KEYMAP=Windows"
		Example:
		cmd /c "appxLoginMgr.exe -install -name=AppxDSLoginManager-8161 -displayName=AppxDSLoginManager-8161 -SockPort=8161 -engine=c:\appx\Appx.exe -AppxApplication=0LA -AppxExecutable=c:\appx\Appx.exe -AppxProcessName=WEBSERVICES -AppxProcessType=SUBROUTINE -AuthenticationMethod=Appx-User -ServiceType=data APPXPATH=c:\appx\data APPX_KEYMAP=Windows"

5) Testing the APPX Data Services interface for connectivity

	Once installed, you can test connectivity by entering the URL's below in a web browser or by using curl (Note: curl is available by default in Windows 10 since 5/2018).  	

		To test connectivity between the browser/curl and APPX Data Services (Note: replace items in <> with the value of your host/ip):
			
			https://<myhost>:<myport>/DsTest	(Note: will return the value OK)
			https://<myhost>:<myport>/DsVer		(Note: will return the APPX Data Services version number in JSON format {i.e. {"Data Services Version":"1.0.0.20021010"} })
			https://<myhost>:<myport>/DsDate	(Note: will return the APPX Data Services service current date/time in in JSON format {i.e. {"LocalDateTime":" 02/10/2020 15:43:31"},{"UtcDateTime":" 02/10/2020 20:43:31"} ))
			
			Note: If you don't have SSL enabled in the "AppConfig" section remove the 's' in https
			
		To test connectivity between the browser/curl and the APPX runtime environment via the APPX Data Services service:

			https://<myhost>:<myport>/api/DateTest			(Note: will return the APPX runtime current date/time in JSON format {i.e. {"DateTime":"02/10/20 15:46 04"} ))
			https://<myhost>:<myport>/api/GetApps			(Note: will return all available APPX applications in JSON format {i.e. {"id":"Application Design","label":"0AD 00 - Application Design","value":"0AD"},... etc, } )
			https://<myhost>:<myport>/api/GetApps?ver=00	(Note: will return all available APPX applications who's version number = '00' in JSON format {i.e. {"id":"Application Design","label":"0AD 00 - Application Design","value":"0AD"},... etc, } )
			
			https://<myhost>:<myport>/api/GetApps?prefix=1			(Note: will return all available APPX applications who's name prefix = '1' in JSON format {i.e. {"id":"ChartDirector Examples","label":"1CD 00 - ChartDirector Examples","value":"1CD"},... etc, } )
			https://<myhost>:<myport>/api/GetApps?ver=00&prefix=1	{Note: will return in JSON format {i.e. {"id":"ChartDirector Examples","label":"1CD 00 - ChartDirector Examples","value":"1CD"},... etc, } )
			
			https://<myhost>:<myport>/api/GetFiles?ap=DMO&ver=00			(Note: will return the files of an APPX application in JSON format {i.e. {"id":"Sales Activity Transactions..","label":"ACTIVITY - Sales Activity Transactions..","value":"ACTIVITY"},... etc, } )
			https://<myhost>:<myport>/api/GetFiles?ap=DMO&ver=00&prefix=A	(Note: will return the files of an APPX application in JSON format {i.e. {"id":"Sales Activity Transactions..","label":"ACTIVITY - Sales Activity Transactions..","value":"ACTIVITY"},... etc, } )
			
			https://<myhost>:<myport>/api/GetFields?ap=DMO&ver=00					(Note: will return the fields of an APPX application in JSON format {i.e. {"id":"Employee Responsible","label":"ACTIVITY ADDED BY - Employee Responsible","value":"ACTIVITY ADDED BY"},... etc, } )
			https://<myhost>:<myport>/api/GetFields?ap=DMO&ver=00&prefix=CONTACT	(Note: will return the fields of an APPX application in JSON format {i.e. {"id":"Added By","label":"CONTACT ADDED BY - Added By","value":"CONTACT ADDED BY"},... etc, } )

