Proxy Use Requirements
If you want to connect the agent through a forwarding proxy, you need to set certain settings, which are located in the Install and Configure the Direct Agent section of the SAS® Customer Intelligence 360 Administration Guide.
If you need to connect the agent through a proxy, set the following properties in the cionprem.properties file. This file is located in the installation directory of the Direct Marketing Agent. (For example, C:\install\CI360Direct or /install/CI360Direct.)
- proxyHost: The host name of the proxy server.
- proxyPort: The port number. The default value is 80.
- nonProxyHosts: A list of hosts that must be connected directly and bypass the proxy. The value is a list of patterns that are separated by |. The patterns can start or end with a * for wildcards. Any host that matches one of these patterns is connected directly instead of through a proxy.
Note: Use the following three properties when the user has an authenticated proxy:
- proxyUser: The user login for the proxy server.
- proxyRealm: The protected area in the proxy where the login and password are valid.
- proxyPassword: The user password for the proxy server.
Here is an example:
proxyHost=foo.demo.sas.com
proxyPort=8181
nonProxyHosts=localhost|fooburger.demo.sas.com
proxyUser=saszsr
proxyRealm =”Access to the staging site"
See the Install and Configure the Direct Agent section of the SAS® Customer Intelligence 360 Administration Guide for more information.
Supported Proxy Authentication
SAS supports the following proxy authentication:
- Basic - The standard mechanism for SAS web products where users enter credentials in a logon dialog box.
- Digest - An authentication type that does not require the password to be transmitted. Instead, the client uses the MD5 hashing algorithm to create a hash and sends it to the Server.
SAS does not support the following proxy authentication:
Allow Domains
In addition, to communicate with SAS Customer Intelligence 360, you must indicate which specific domains to allow in your firewall depending on the action that you want to perform. The Task 6: Allow Domains section of the SAS® Customer Intelligence 360 Administration Guide lists the domains that need to be allowed.
It is important to include ALL the information for your regions and for the actions that you want to take. Make sure to scroll down the page and include all the actions that you need. Here is an example:
SAS® 360 Engage: Direct
- Segment downloads for only direct marketing.
- Segment uploads for only direct marketing.
- Static link node list uploads and downloads only for direct marketing.
Issue Symptoms
The following symptoms might occur when there are issues with the Direct Marketing Agent:
- TimeoutException
- errors getting sessions (sid is null)
- segment downloads and uploads for direct marketing do not work
- INVALID_PROXY_CALLBACK
Errors and Messages
onprem_direct.log Messages
The following messages might occur in the onprem_direct.log:
Event stream connection to gateway failed: java.util.concurrent.TimeoutException: Idle timeout expired:
errorCode: GATEWAY_CONNECTION_FAILED, message: java.util.concurrent.TimeoutException: Idle timeout expired:
When traffic flows regularly over the WebSocket, the connection stays up. However, the connection has issues when there is an idle period. In this scenario, the gateway sends a "ping" every 60 seconds. In this idle case, the agent never receives the ping from the agent logs. As a result, when the gateway does not receive a response to the ping within 30 seconds, it closes the connection and also has an idle time-out. (Note that the agent does not get a close event either). Then, once the agent does not receive a message for 70 seconds, it closes its end of the connection and tries to reconnect.
This message likely occurs because there is network equipment between this agent and the gateway that has an idle time-out shorter than ten minutes. That equipment closes the WebSocket connection when it reaches its idle time-out, which is hit because the gateway pings come only every 70 seconds when there is no other traffic to be sent. At that point, a new connection has to be made to get traffic to flow again.
To circumvent this message, try to increase the firewall time-out to more than one minute.
org.jasig.cas.client.validation.TicketValidationException: INVALID_PROXY_CALLBACK
This message occurs because the SAS Customer Intelligence OnPrem Direct Services is pointing to the wrong host name and needs to point to the fully qualified host name where the Direct Marketing Agent is running.
Common Proxy Errors
407 Proxy Authentication Required
The client must authenticate with the proxy server before the request can be processed. This error can be the result of missing or incorrect credentials.
429 Too many Requests
The gateway returns this error when a user has made too many REST requests of a particular type within the current 30-second window.
To circumvent this error, spread out the time of the requests.
Other General Errors
These errors can occur regardless of whether you do or do not use proxies:
400 Bad Request
This error occurs when the proxy server cannot understand the request, which can be the result of any of the following:
- Incorrect formatting or syntax errors, making them unreadable by the server.
- The URL contains invalid characters or is improperly formatted.
- The request is too large for the server to handle (large files or excessive data).
- There are corrupted or invalid cookies that the server rejects.
- An incorrect HTTP header (request or response) is improperly formatted or contains incorrect values.
403 Forbidden
This error occurs when access to resources is denied, which can be due to any of the following:
- blocked ports
- blacklisted sites
- restricted access policies
502 Bad Gateway
This error occurs when the gateway or proxy server receives an invalid response from an upstream server. This error indicates that the upstream server is reachable but returned an unexpected or invalid response, which can be due to any of the following:
- Server overloads – The server is overwhelmed with too many requests.
- Technical issues on the destination server or upstream server. The destination server is the server that the gateway or proxy is trying to communicate with to fulfill the client’s request.
- The server is unavailable due to maintenance or problems.
- Network connectivity issues occur between the gateway and destination server.
- A firewall blocks the communication between servers.
- The Domain Name System (DNS) prevents the gateway from finding the destination server.
To circumvent 502 errors, try any of the following workarounds:
- Refresh the page.
- Clear the browser cache.
- Check the network connection.
- Try another browser.
- Ask a coworker to try the same steps that you took on their system.
- Check the firewall logs.
- Review the firewall rules and make sure that the ports and IP addresses are allowed.
- Contact the website support team.
503 Service unavailable
The proxy server cannot access the required service, which can be due to any of the following:
- server maintenance
- overloads
504 Gateway Timeout
This error occurs when the gateway or proxy server does not receive a timely response from the upstream server. This error indicates that the upstream server is reachable but did not respond in time, which can be due to any of the following:
- server overload
- server downtime
- network issues
- firewall blocks
- DNS issues
To circumvent 504 errors, try any of the following workarounds:
- Refresh the page,
- Try another browser,
- Ask a coworker to try the same steps that you took on their system.
- Restart the router or computer.
- Contact the website support team.
- Contact the network administrators.
Troubleshooting
The Direct Marketing Agent Was Working But No Longer Works
If the Direct Marketing Agent worked previously but you encounter an issue where it no longer works, consider the following:
- Has anything recently changed in the environment? For example, an upgrade of an agent, network changes, system updates, modifications to SAS® Management Console, and so on.
- Check the status 360 page to make sure that there are no known issues for the Execution of Direct Marketing Tasks and Segment Maps: https://status.360.sas.com/.
- For example:
- issues with Direct Agent connectivity
- issues with Direct Agent connectivity degraded performance
- incident status
- degraded performance
- components
- execution of Direct Marketing tasks and segment maps
- Verify that no one has modified the proxy settings recently (cionprem.properties). Also, check the credentials.properties if you connect through an authenticated proxy. The client secret should match what is defined in the Access Point in the SAS Customer Intelligence 360 user interface (UI). If you are using JSON Web Tokens (JWT), it is still recommended to match the clientSecret.
- From the onprem directory, change to the logs directory, get the corresponding log, and review for errors (onprem_direct.log.<date> ).
- Contact your network team to see if they are getting additional messages or are aware of any known issues or changes that might be causing issues.
- As a best practice, always make sure that you are using the latest version of the Direct Marketing Agent.
Additional Troubleshooting
A good way to troubleshoot is to run the following curl command on the server where the Direct Marketing Agent is installed. If the curl command works, it does not mean that all is well with the proxy server. However, it is a good place to start in order to understand where the issue might be.
curl -U "user-id":"pwd" -v -x proxy-name:proxy-port "https://extapigwservice-prod.ci360.sas.com/marketingGateway/commons/ping" --proxy-anyauth
Note: The values used for "user-id", "pwd", “proxy-name”, and “proxy-port” need to be the same values found in the cionprem.properties or credentials.properties files.
If the proxy server does not require authentication, remove “-U "user-id":"pwd"” from the curl command.
