Set Up and Manage Agent

 

ON THIS PAGE      Show

 

 

 

 

How do I download an agent?

See Download and Register Agent in "Getting Started".

Can I launch the agent from a command prompt?

  1. Open an elevated/admin command prompt on Windows or use sudo on Mac or Linux.

  2. Change to the directory where the agent jar file is located; for example, on Windows:

    cd LOCATION_OF_AGENT

  3. Run the following command to register the agent:

    java -Xms512M -Xmx1G -jar agent.jar key:API_KEY

Once the agent is registered, you can assign a profile to the agent.

 

  Note

 

If you have set a default profile, your agent will automatically start ingesting using the settings from that profile right after you register the agent with the configuration dashboard.

 

 

 

How can I run the agent using a proxy server?

Since the agent bypasses proxy server settings configured on your machine, use the following command line syntax to run the agent using a proxy server:

java -Xms512M -Xmx1G -Dhttp.proxyHost=HOSTNAME -Dhttp.proxyPort=PORT -Dhttps.proxyHost=HOSTNAME -Dhttps.proxyPort=PORT -Dhttp.proxyUser=USERNAME -Dhttp.proxyPassword=PASSWORD -jar agent.jar key:API_KEY

How do I assign a profile to an agent?

You can do either of the following:

  • On the configuration dashboard, next to the agent name, select the profile name from the Content Profile list and click Save.

  • On the dashboard, click an agent name to display the Manage Ingest Agent page, select a content profile from the Content Profile list and click Save Agent.

 

  Note

 

If you save your agent with the blank row selected from the Content Profile list, the agent is automatically assigned a default profile.

 

 

 

Can I set a default profile for all new agents?

Yes. See How do I set a Default profile?

How do I start ingesting content?

Click Start Ingestion on the Manage Ingest Agent page.

 

  Note

 

If you have set a default profile, the agent starts ingesting content automatically right away after you register it with the configuration dashboard.

 

 

 

See also Restarting Ingestion.

What does the agent status mean?

The agent status is displayed in the list of Contest Ingest Agents on the dashboard and on the Manage Ingest Agent page:

 

  Status: On / Ingesting

 

The agent is currently ingesting content.

 

 

 

 

  Status: Idle

 

The agent is running, but is not ingesting content. A status of "Idle" is normal if no new content has been published to your selected entitlements. However, if your agent has stopped ingesting content, or has been idle for an extended period of time, see My agent is idle. How do I restart ingesting content?

 

 

 

 

  Status: Off

 

The agent has not communicated with the AP Media API server for a significant amount of time, which indicates that the agent may not be running. See My agent stopped. How do I restart ingesting content?

 

 

 

How do I stop ingesting?

To stop ingesting from the configuration dashboard:

Click Stop Ingestion on the Manage Ingest Agent page.

To stop ingesting from the Agent Management page on the local host:

  1. Access the Agent Management page on your local host; for example, localhost:8087/agent.

  2. Click Stop Ingesting.

How do I stop the agent from running?

You can stop the agent process running in the background (whether the agent is ingesting or not).

 

  Important

 

  • Stopping the agent process would require it to be restarted either through double-clicking the agent jar file or from the command line before that agent would be able to ingest again.

  • Once you stop the agent process, you will no longer be able to access the Agent Management page on your local host.

 

 

 

To stop the agent process:

Do either of the following:

  • From the command prompt, use CTRL-C.

  • Close the command prompt window.

Restarting Ingestion

My agent is idle. How do I restart ingesting content?

A status of "Idle" is normal if no new content has been published to your selected entitlements. However, if your agent has stopped ingesting content, or has been idle for an extended period of time, do one of the following to restart ingestion:

To restart ingesting from the configuration dashboard:

  1. On the dashboard, click an agent name to display the Manage Ingest Agent page.

  2. Make sure a profile is assigned to the agent.

  3. Click Start Ingestion.

To restart ingesting from the Agent Management page on the local host:

  1. Access the Agent Management page on your local host; for example, localhost:8087/agent.

  2. Click Start Ingesting.

My agent is off. How do I restart ingesting content?

If the agent process is no longer running, do one of the following to restart ingestion:

From your desktop environment:

  1. Browse to the folder where you saved the agent jar file and double-click the file name.

  2. Restart ingestion either from the configuration dashboard or from the Agent Management page on the local host.

From the command prompt on Windows or with sudo on Mac or Linux:

  1. Change to the directory where the agent jar file is located; for example, on Windows:

    cd LOCATION_OF_AGENT

  2. Run the following command:

    java -Xms512M -Xmx1G -jar agent.jar

  3. Restart ingestion either from the configuration dashboard or from the Agent Management page on the local host.

How do I access the Agent Management page on the local host?

To determine where the Agent Management page is located on your local machine, use the local port you noted when registering the agent. For example, if your agent registration address is localhost:8087/register, you can manage your agent from your local machine at localhost:8087/agent.

 

  Tip

 

If you are running multiple agents on the same machine, the local port number will be unique for each agent, and you will need to manage each agent from a separate Agent Management page; for example, localhost:8087/agent, localhost:8080/agent and localhost:8081/agent.

 

 

 

Can I change the local port that the Agent Management page uses?

Yes, you can specify the port to use from the command prompt on Windows or with sudo on Mac or Linux; for example:

java -Xms512M -Xmx1G -jar agent.jar setPort:8088

How can I disable the local Agent Management page server?

From the command prompt on Windows or with sudo on Mac or Linux:

  • To disable the local HTTP server:

    java -Xms512M -Xmx1G -jar agent.jar localHTTP:false

  • To enable the local HTTP server:

    java -Xms512M -Xmx1G -jar agent.jar localHTTP:true

From the configuration dashboard:

  1. Click the agent name on the dashboard to display the Manage Ingest Agent page.

  2. Click the Agent Local HTTP Settings tab.

  3. Select the Disable Agent's local HTTP Server check box to disable the local HTTP server or clear this check box to enable the server.

What is Access Mode?

Access mode determines the AP Media API version that the agent uses to download content.

  • Default mode is the current stable release of the API. This mode is automatically selected from the Access Mode list on the Content Ingest Agent page, and you do not need to change this setting to stay on the latest stable version of the API. The version will be updated automatically once a new stable API release becomes available.

  • Preview mode may be used to test new features in the upcoming API version. In this mode, the agent will automatically use the latest available version, which may either be an upcoming API version whenever it becomes available for testing or the Default version when there is no new version to try.

How can I preview the upcoming API version?

To test your agent with the upcoming API release:

  1. On the dashboard, click an agent name to display the Manage Ingest Agent page.

  2. Make sure a profile is assigned to the agent.

  3. Select "Preview" from the Access Mode list:

  4. If the agent is currently ingesting, the ingestion will automatically switch to the preview version of the API. If the agent is currently not ingesting, click Save Agent, and then click Start Ingestion to start ingesting content.

How do I start ingesting from a specific point in time?

By default, the agent begins ingesting content from the present time. If you stop content ingestion, or if it is interrupted for any reason, the agent saves the last ingestion time for each entitlement to maintain continuity, that is, to avoid any gaps and/or overlaps in content ingestion. When you restart content ingestion, the agent begins ingesting content for each entitlement from the last ingestion time. If more than three days have passed since the last ingestion time, the agent starts ingesting from the oldest content available.

In some cases, you might want to change the starting time for content ingestion; for example, if you added more entitlements or if there is not enough time to ingest all content since the last ingestion time before the newspaper's release deadline.

To change the starting time for content ingestion:

  1. On the dashboard, click an agent name to display the Manage Ingest Agent page.

  2. Make sure a profile is assigned to the agent.

  3. Select an option from the Reset Ingestion list to specify a timeframe to reset the ingestion time for this agent, and then click the Reset Ingestion icon:

  4. If the agent is currently ingesting, the ingestion will continue from the specified time. If the agent is currently not ingesting, click Save Agent, and then click Start Ingestion to start ingesting content.

How do I delete an agent from the dashboard?

 

  Note

 

You can delete an agent from the configuration dashboard after it has been off for a certain period of time (currently after two hours).

 

 

 

Do either of the following to delete an agent:

  • On the dashboard, under Content Ingest Agents, click Details for the agent that you want to delete, click Delete Agent, and then click OK to confirm.

  • On the dashboard, click an agent name to display the Manage Ingest Agent page, click Delete Agent on the right-hand side of the agent details section, and then click OK to confirm.

Can I manage the agent remotely?

Yes, to manage the agent remotely, you can use the IP address found on the Agent Management page on your local host; for example, at localhost:8087/agent.

Agent Details and Statistics

Where can I view agent details?

On the dashboard, click the agent name to display the Manage Ingest Agent page.

Right below the agent status, you can view the agent details:

  • Last Communication. The date and time (local time) when the agent was last run.

  • Last Feed Request. The date and time (local time) when the agent last requested a feed from the AP Media API server.

  • Operating System. Operating system (OS) of the machine where the agent is installed.

  • IP. The IP address of the machine where the agent is installed.

  • Hostname. The hostname of the machine where the agent is installed.

  • Java Version. Java version of the machine where the agent is installed.

  • Agent Version. The agent's version.

  • Agent ID. The agent's ID.

  • Base File Path. The path to the folder where the agent jar file is located.

Are agent statistics available?

Yes. To view agent statistics, click the agent name on the dashboard to display the Manage Ingest Agent page.

Agent statistics are displayed below the agent details:

 

  Note

 

By default, agent statistics are displayed for all entitlements assigned to the profile that the agent is using. To view statistics for a specific entitlement, select it from the Statistics for menu and click Update Statistics.

 

 

 

The following statistics are reported for the last 24 hours:

  • Feeds. The number of feeds pulled from the server. This number does not reflect the actual number of feeds that have been saved.

  • Files. The total number of text stories and media files saved.

  • Errors. The total number of errors received.

  • Warnings. The total number of warnings received.

The graphs show the agent health in the last 24 hours; for example:

When the agent is running, the Feeds graph remains at a near constant level. Any gaps in the Feeds graph would indicate that the agent was not actively ingesting during that time period.

The pie charts show downloads by media type and format.

Where can I see the most recent errors and warnings?

Click the agent name on the dashboard to display the Manage Ingest Agent page, scroll down, and then click the Errors and Warnings tab to see the five latest errors and warnings.

If the agent is running, but no messages are displayed, click Get Errors and Warnings to load the latest messages.

Can I download the agent logs?

Yes, you can download agent logs in bulk or one by one.

To download log files one by one:

  1. Click the agent name on the dashboard to display the Manage Ingest Agent page, scroll down and click the Agent Logs tab:

  1. (Optional) To filter the logs by date, select the date from the Specify Date menu, and then click Get Logs.
  2. Click for the log that you want to download.

 

  Note

 

The agent uploads its logs every five minutes. Click Get Logs to display the latest.

 

 

 

To download log files in bulk:

  1. On the Agent Logs tab, click Bulk Download.

 

  1. Do one of the following:

    • To download log files from the last few hours, select By Period from the Set Criteria menu, and then select the period from the Specify Time menu:

    • To download log files from a specific date, select By Date from the Set Criteria menu, and then select the date from the Specify Date menu:

  1. (Optional) To place all of the logs into a single file instead of separate files, click the Merge Content slider to select it:

  1. Click Download.

Where can I see the agent health check status?

Click the agent name on the dashboard to display the Manage Ingest Agent page, scroll down and click the Health Check Report tab. By default, the report contains the health check information from the latest log file; for example:

The data on the Health Check Report tab is not refreshed automatically.

To refresh the data manually:

Click Get Latest Report(s).

To display the data for additional log files:

Click the down arrow next to No. Reports, select the number of the most recent reports to display, and then click Get Latest Report(s).

 

  Note

 

The health check report is available only for agents that have logs.

 

 

 

What information is available on the Agent Management page on the local host?

The following information is available on the Agent Management page on your local host:

  • Profile ID. Unique configuration profile ID.

  • Profile Modified. The date and time that the profile was last modified on the configuration dashboard.

  • IP Address. The IP address of the machine where the agent is installed.

  • Default Base File Path. The base file path for saving content files that you specified on the dashboard.

  • Agent Config File Path. The path to the local configuration files that allows you to review the configuration that the agent is currently using.

 

 

  Important

 

 

Do not modify or delete the local configuration files. Changing the settings in these files or deleting them may produce unexpected results.

 

 

 

 

  • Feed File Path. The path to the folder where JSON feeds are saved.

  • Log File Path. The path to the log folder.

  • Environment. The environment from which the agent is downloading content.

Running Agent as a Service

 

  Important

 

To run the agent as a service:

  • You must have admin privileges on Windows or root privileges on Mac or Linux.

  • The JAVA_HOME environment variable must be set (defining the path to your JAVA folder).

 

 

 

You can run the agent as a service on Windows, Mac or Linux. When the agent is running as a service, it restarts automatically when your machine is restarted.

How do I install the agent as a service?

  1. Run the agent jar from the admin command prompt on Windows or with sudo on Mac or Linux and register the agent's API key.

  2. At the bottom right of the Agent Management page on your local host, click Run agent as a service and wait for the install process to complete.

 

 

  Tip

 

 

Alternatively, you can install the agent as a service from the command prompt on Windows or with sudo on Mac or Linux:

java -Xms512M -Xmx1G -jar agent.jar service install

 

 

 

 

The service will start automatically.

How do I start and stop the service?

Once the agent is installed as a service, you can start or stop it as any other service process. For example, on Windows, you can start and stop it from the Task Manager by right-clicking the service name and clicking Start Service or Stop Service:

 

  Tip

 

Starting and stopping services from the Task Manager requires admin privileges. You can click Show processes from all users at the bottom of the Task Manager window to switch to the admin mode.

 

 

 

Alternatively, you can start and stop the service from the command prompt on Windows or with sudo on Mac or Linux.

To start the service:

java -Xms512M -Xmx1G -jar agent.jar service start

To stop the service:

java -Xms512M -Xmx1G -jar agent.jar service stop

How do I uninstall the service?

You can uninstall the service from the command prompt on Windows or with sudo on Mac or Linux:

java -Xms512M -Xmx1G -jar agent.jar service uninstall

Can I install more than one agent as a service?

Yes, you can install multiple agents as a service from the command prompt on Windows using the servicename parameter; for example:

java -Xms512M -Xmx1G -jar agent.jar servicename:MediaAgent1 service install

java -Xms512M -Xmx1G -jar agent.jar servicename:MediaAgent2 service install

If you are running multiple agents as Windows services, you can use the servicename parameter to start, stop or uninstall a specific service on Windows; for example:

java -Xms512M -Xmx1G -jar agent.jar servicename:MediaAgent1 service start

java -Xms512M -Xmx1G -jar agent.jar servicename:MediaAgent1 service stop

java -Xms512M -Xmx1G -jar agent.jar servicename:MediaAgent2 service uninstall