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?

Yes. To start the agent 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 -jar agent.jar

The Register Agent page opens in your browser prompting you for an API key.

 

  Tip

 

Alternatively, you can provide the API key as a command-line argument:

java -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 -Dhttp.proxyHost=HOSTNAME -Dhttp.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 Agent 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 Agent 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).

 

  Caution

 

  • 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 Agent 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 Agent 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 -jar agent.jar

  3. Restart ingestion either from the Agent 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 -jar agent.jar setPort:8088

Can I disable the local Agent Management page server?

Yes, you can disable and enable the local HTTP server from the command prompt on Windows or with sudo on Mac or Linux:

To disable the local HTTP server:

java -jar agent.jar localHTTP:false

To enable the local HTTP server:

java -jar agent.jar localHTTP:true

What is Access Mode and Version?

Access mode and version determine the environment (for example, 'Live' or 'Preview') and AP Media API version which the agent uses to download content. 'Live' mode is the default. 'Preview' mode may be used to test new features.

It is typically recommended to use the default mode and version already selected from the Access Mode lists on the Content Ingest Agent page.

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 Agent Configuration 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 Agent Configuration 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 available from the last three hours. See also How do I change the timeframe for which statistics are reported?

 

 

 

The following statistics are reported for the specified timeframe:

  • Requests. The number of feeds pulled from the server. This number does not reflect the actual number of feeds that have been saved.
  • Artifacts. The total number of text stories and media files saved.
  • Text Stories. The number of text story files saved, including NITF and ANPA files.
  • Pictures. The number of picture files saved.
  • Graphics. The number of graphic files saved.
  • Videos. The number of video files saved.
  • Audio. The number of audio files saved.
  • Total Errors/Warnings. The total number of errors and warnings received.
  • Last Error/Warning Time. The date and time of the last error or warning (local time).
  • Last 5 Errors/Warnings. The last five error/warning messages.

How do I refresh agent statistics?

In the Agent Ingest Statistics section of the Manage Ingest Agent page, click the Refresh Agent Statistics icon next to the Statistics from list.

How do I change the timeframe for which statistics are reported?

In the Agent Ingest Statistics section of the Manage Ingest Agent page, select the timeframe from the Statistics from list.

How do I reset statistics?

In the Agent Ingest Statistics section of the Manage Ingest Agent page, click Reset Statistics.

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 AP Media Agent 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 AP Media Agent Configuration 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

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.

 

  Important

 

To run the agent as a service, you must have admin privileges on Windows or root privileges on Mac or Linux.

 

 

 

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 -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 -jar agent.jar service start

To stop the service:

java -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 -jar agent.jar service uninstall