Contents
Reviewing Connections/Sessions
The SuccessWare21® API (SWAPI) is distributed with each SuccessWare®21 installation. SWAPI is an NT Service application and must be installed/administered/operated on your server (not a workstation). You must be logged on as an administrator when installing, configuring, and starting the service. Your administrator account must also have access to the MSSQL Database Server and the SuccessWare21® Databases.
SWAPI can be installed and started from within the SuccessWare®21 application when it is run on the server where SucessWare®21 is installed (not a workstation). You access the SWAPI Server Administrator to install, configure and start the service.
1) At your server, Launch SuccessWare®21.
2) Access the main menu and select Add-On Manager, from the My Add-Ons screen click the SWAPI Server link. This will launch the SWAPI Server Administrator. You must have administrative ability in order to access this option.
SWAPI runs as a NT Service. You cannot access “Properties” to configure the service until the service is installed on the server. To install the service, click “Install”.
Once installed, the status in the Administrator will show “Stopped”. This indicates that the service in installed but not running. Once installed you can configure your service.
Once installed, before starting the service, you must configure it by clicking the “Properties” button.
Select the port number on which you want your SuccessWare21® SWAPI Server to operate (2142 is recommended). Port forwarding to this port number on this machine’s IP address will be required if the SuccessWare21® SWAPI Server will be accessed from the internet. You will need your network administrator or internet service provider to set this up. Specific knowledge of your network router, firewall, or internet access will be required.
NOTE: If you do not enable SSL, an SSL port is automatically enabled one port above the port you select here. If you select port 2142 here, then port 2143 will also be opened for SSL communications.
1) Select or enter the name of your SQL Server. When the SQL Server name is the same as the Machine name, you need only enter the Machine name. Otherwise, you will need to enter both: “<machine name>\<sql server name>” (do not include the quotes).
2) Select your authentication mode, this should be the same as the user that you configured SWAPI Server to run as.
a. If you choose SQL Server authentication, then you must enter a user name and password
3) Click the “Test Connection” button. A message box should appear that says “Connected successfully.”
a. When testing the connection using Windows authentication, the test will be conducted using the credentials of the user that is logged into the server. Ideally this should be the same user that you configured the SWAPI service to run as.
If the test is not successful, ensure that you have the correctly identified your SQL Server, and if using SQL authentication have entered the correct user name and password. When using Windows authentication ensure that the logged in user has permissions to connect to the database.
The following advanced configuration settings are available but the default values should suffice. To access these configurations, check the Show Advanced Settings box.
You should leave the Log to Text Files s box unchecked. It is only used on rare occasions for trouble shooting. SWAPI Server can maintain a log of requests and responses in text files. These files are stored in a folder called “logs” underneath the SWAPI Server Administrator folder. You cannot change this setting.
NOTE: Using SSL is strongly recommended.
The SuccessWare21® SWAPI Server can perform data encryption with SSL. Before activating SSL, check to make sure your third party solution supports SSL encryption.
To activate SSL, check the SSL only box. Default Certificate Files and Keys are included and can be used to perform data encryption. If you understand enough about SSL Certificates and Keys, and you can obtain or create your own certificate, you can use this page to specify your Certificate File, Key File, Root Certificate File, and Password.
Once installed and configured, you can start the service by clicking the “Start” button. The service will always be running unless you stop it or uninstall it. The service will automatically start in the event that the server is rebooted.
Once the service is started, you can test the service. This test is only required to test port forwarding to ensure that the service can see the internet, and the internet can see the service.
Click the “Test” button. A request will be sent over the internet to a SuccessWare Server, telling the server your SuccessWare21® SWAPI Server’s IP address and port settings. The SuccessWare Server will then attempt a connection to your SuccessWare21® SWAPI Server at that IP on that port. You should receive one of three messages in response to the Test:
1. Unable to access SuccessWare’s test server
2. An error was encountered accessing SuccessWare’s test server
3. The SuccessWare test server received your test request but was unable to connect with this service over the internet as a client. Check to make sure the correct port is open/forwarded to this system.
Messages 1 and 2 indicate that the server does not have access to the internet. Message 3 indicates that your firewall/router port forwarding is not setup properly.
Once you have tested successfully, you have completed the installation/configuration of the service. Third party agents can now attempt to access SuccessWare21®. They will be denied access until a SuccessWare21® Administrator explicitly grants access to the individual agent via the Agent Manager.
The Agent Manager controls agent access to SWAPI. To open the Agent Manager, you must have administrative rights with in SuccessWare®21. Select from the main menu: “Setup | Utilities | Administrative Tools | Agent Manager”. Third party agents cannot access SWAPI until a SuccessWare®21 user, having administrative ability, expressly enables the individual agent access via the Agent Manager. The Agent Manager lists all agents that have attempted to connect to SWAPI. To grant access to a new agent, that agent must first attempt to connect to SWAPI.
Once an agent attempts to access SuccessWare®21, it will show up in the Agent Manager. The SuccessWare®21 SWAPI Server must be running for a third party agent to access SuccessWare®21.
The first time an agent attempts to connect, the connection will fail with the message “The agent [AGENT01] was not registered and does not have permission to access the server”. Subsequent attempts to connect will continue to fail, with the message “Invalid password for agent”, until the agent is given access via the Agent Manager by a SuccessWare®21 user.
To grant access
1. Select the agent record in the top grid. If you do not see a record for the agent, the agent has not yet attempted a connection to your databases. In order for the agent to connect, you must provide the agent with your Master ID (Customer ID from the SuccessWare® Activation form).
2. Enter a password for the agent in the top grid of the Agent Manager. This password will need to be supplied to the third party provider in order for their software to properly access SuccessWare®21. This is how you, as a SuccessWare®21 Administrator can control grant/deny third party access to your data.
3. Enable access to individual companies by double-clicking the line in the lower grid for the specific company. Each double click will toggle the state between enabled/disabled. The state must show enabled “true” for the agent to access the specific company’s database.
4. Enable or disable messaging. If enabling messaging, specify the forwarding URL address of the third party server application.
Note: Enabling messaging manually is not normally necessary. The third party agent can automatically enable or disable messages during its connection process. You should only enable messaging if the agent specifically asks you to and provides you with a forwarding URL.
Successware®21 will post messages for third party applications. Messages posted include the following…
l A reference library change is made
l An assignment scheduling change is made for the current date.
l The pricebook is modified, item numbers, prices, descriptions changed.
The messages are recorded so that they might be retrieved by the third party application. Messages will be recorded for any agent with Messaging Enabled in the Agent Manager. The SuccessWare®21 SWAPI Server will forward these messages to the Server URL if specified for that agent in the Agent Manager.
Click on the “Connections” button at the bottom of the Agent Manager to review the connections for the selected agent. From the Agent Connection Manager, you can review sessions for selected connections, refresh and disconnect sessions and connections. This manager is meant to reset connections/sessions as a maintenance feature if they should become stuck. This manager can also be used to terminate sessions/connections to stop access to the SuccessWare®21 databases by third party agents.
NOTE: Third party agents cannot access the SuccessWare®21 databases without a SuccessWare®21 user expressly enabling access to the agent via the Agent Manager.
User Logon Enabling controls how users are allowed to access or logon to the SuccessWare21® database. It is possible for users to logon to the SuccessWare21® database via SuccessWare21®, or some third party agent. You can control this access in Setup | Users | Groups. The User Group form has a tab page for “Logon”.
If you do not check the “Allow logon to SuccessWare21” checkbox, users that belong to this group will not be allowed logon permission to SuccessWare21. If you check/uncheck the checkbox for an agent in the third party agent list, users belonging to this group will be allowed/denied permission via the third party agent.
NOTE: Agents will not appear in User Group Setup until they have attempted access and registered with the SuccessWare21® database.
User Logon Enabling can be accessed from the 13th tab of the User Group Setup within SuccessWare21®.
User Group Setup is accessed from the Group button in the User Setup Form: from the main menu, “Setup | Users | Groups | Logon-13”