The Direct Marketing agent is an on-premises component that processes requests to and from SAS Customer Intelligence 360 running in the cloud. The agent uses an information map and the customer data mart to process the requests. It also connects to the Direct Access Point, which defines the security information that is required by the Direct Marketing agent.
In this article, we will focus on the following topics:
- common issues that you might experience with the Direct Marketing agent
- what to look for in the logs
- whether restarting the Direct Marketing agent is a good first step to troubleshooting an issue
Common Direct Marketing Agent Issues
The Direct Marketing agent can encounter various issues due to a myriad of reasons. We highlighted some of the common issues that you might experience and what these issues could mean.
Connectivity Issues
Symptoms of agent connectivity issues are varied, but a concrete example of this issue include fields or values that are grayed out and are unable to be selected. When this issue occurs, check the Agent Status in the user interface by navigating to General Settings ► External Access ► Access Points. Click the View agent status icon on the rightmost column of the agent. You will most likely see one of the messages about the Direct Marketing agent:
“The agent is running.”
or
“That status of the agent is unavailable. The agent may not support retrieving status.”
Unsupported Agent Version
The Direct Marketing agent has a backward compatibility of three versions from the current release. Use the version command to show the agent version and gateway version if the agent is connected to the gateway. This command also writes the versions that are supported by the gateway. If the agent version is in the losing gateway support list, you should upgrade the agent.
Check for the following messages in the onprem_direct log:
startAgent - connecting event stream with gateway extapigwservice-<server>.ci360.sas.com
Direct Marketing Agent started.
Stream closed GATEWAY_CONNECTION_FAILED: 1007: CIException:MKTCMN74265:[MKTCMN74265] ERROR_UNSUPPORTED_AGENT_VERSION
Upgrade Failed
You can use operating system specific scripts to upgrade the existing agent to the latest version. You can find these scripts in the install directory for the Direct Marketing agent. The scripts are named upgrade_app.bat (for Windows) and upgrade_app.sh (for UNIX). Before running these scripts, ensure that the existing agent is stopped. An error occurs if an upgrade is attempted while the agent is running. If the upgrade fails when you run either the upgrade_app.bat or the upgrade_app.sh script, you must manually delete the new folder that was created in the agent installation directory before running the upgrade script again. In some cases, you need to delete the new directory on Windows if there are not enough permissions on the folders for the user running the upgrade_app.bat script.
Note: The upgrade process backs up any files that might be overwritten into a zip file, which are located in the dmAgentBackup<datetime>.zip. agent root directory.
Check for the following messages in the upgrade log:
Upgrading file: upgrade_app.bat
Upgrading file: upgrade_app.sh
Upgrading file: dm.sh
Upgrading file: logging.properties
Failed to overlay new files onto agent.
Gateway Time-Out
A gateway time-out occurs when the agent and the gateway fail to connect. Usually, this time-out occurs because of network connectivity issues in the on-premises environment. When the gateway works correctly, the communication between the agent and the gateway is established and kept open through application-level pings. The gateway sends out these pings to the agent, which responds with an acknowledgement. A network issue causes the websocket connection and any subsequent gateway time-outs to occur when the agent tries to reconnect.
We recommend that you set the idle time-out settings for any network device between the server for the agent and the internet to greater than one minute. Idle time-out settings that are less than one minute might cause the network device to drop the connections between the agent and the gateway in the cloud. This behavior can happen because the connection might not have any traffic for a minute. When the idle time-out settings are set to greater than one minute, the Direct Marketing agent has more time to acknowledge the pings and will attempt to reconnect.
Check for the following messages in the onprem_direct log:
startAgent - Direct Marketing Agent started.
Event stream connection to gateway failed: Connect Timeout
streamClosed - errorCode: GATEWAY_CONNECTION_FAILED, message: Connect Timeout
HTTP 500 Internal Server Error
The HTTP 500 internal server error can be misleading because the error means that the server was unable to process the request due to an unforeseen circumstance. There can be many varied reasons for why this error occurs such as a probable issue with the SAS Customer Intelligence 360 system or errors with metadata generation. These errors can also come from the SAS Customer Intelligence 360 cloud APIs.
Check for some of the following error message variations in the onprem_direct log:
HTTP Status 500 – Internal Server Error
Error completing request: org.springframework.web.client.HttpServerErrorException: 500 Internal Server Error
org.springframework.web.client.HttpServerErrorException$InternalServerError: 500 : [no body]
Can I Restart the Direct Marketing Agent?
Restarting the Direct Marketing agent might be a good first step to troubleshooting the issue that you are encountering. However, this workaround does not always resolve the issue. In most cases, it is helpful to check the onprem_direct.log found in the <SAS-configuration-directory/DM-agent-directory/logs folder first, which helps you isolate the problem. Often, the root cause might be with the SAS platform or SAS Web Application Servers. Note that restarting the SAS platform requires that the Direct Marketing agent be restarted too.
The following error indicates that the Direct Marking agent login failed to create a session (session ID is null). This error could be a result of the platform being unhealthy, or the agent was potentially configured with a bad username or password.
022-05-18 11:47:35,383 ERROR [pool-18-thread-26] SID[] USER[] CC[] [] agent.service.DirectMarketingTaskService - Unable to execute: java.lang.RuntimeException: com.sas.analytics.crm.error.client.CodingException: sid is null.
For additional help, contact SAS Technical Support by creating a track with the Contact Support option in the SAS Customer Intelligence 360 user interface.
