Using the Command Line Interface for Push Messaging

This section provides information on using the push command line interface. The push command line tool is useful for scripting and batch processing. It enables you to manage push messages across multiple Good Intranet Servers.

Setting Up Push Messaging

The following is an overview of the steps you take to prepare for using push messaging on the command line. Step details will vary depending on how you plan to integrate push into your corporate environment.

To set up push messaging:

1. Determine which hosts on your network can be used to send messages. A host machine does not have to be running Good Intranet Server to send command line push messages.

To configure additional hosts for sending pushed messages, update the push.alllowedhosts property in the Good Intranet Server properties file (install_dir\config.props) to include these hosts. For example:

push.allowedhosts host_1 host_2 host_3

For details, see Configuring Hosts

2. Create a script (or some other application interface) to initiate push.

Good Intranet includes a command line utility to send push messages, but you can also include push commands in script (for example, a Perl script or .bat file).

Push commands include:

• Submit (Push)
• Cancel
• Status
• Listen
• Report

See below for a detailed description of push command syntax.

3. Determine the URL location for the file or web resource that contains the push content.
4. Prepare email addresses.

You can enter individual email addresses on the push command line. However, for multiple recipients, you may prefer to set up a side file or script with a list of email addresses.

5. Monitor push messages as desired.

You can use the Status command to check the status of individual messages or the Report command for detailed push reports.

Invoking Push Commands

You can enter push commands directly on a command line or include it in a script. To run from the command line:

1. From the Good Intranet Server installation directory, enter the following:

jre\bin\java com.good.push.tools.Command

Where Command is a specific push command with arguments. For example:

jre\bin\java com.good.push.tools.Cancel -push-id=N56679

Note: For command options that require spaces within (or between) arguments, you need to put quotes at the beginning and end of the arguments. For example, -address="jvc@office.com rmiller@oop.com"

Sending Push Messages

The Submit command sends a push message to the push server for delivery to handhelds. This message can be any content type and can be pushed to one or more handhelds (identified by email addresses).

To send a push message:

1. Create a URL location that contains the push content.
2. Use the following command to send a push message:

You can enter the command directly on a command line or include it in a script.

Commands (with associated arguments and options) should be entered on one line (no carriage returns).

jre\bin\java com.good.push.tools.Submit -address="address..."
-url=url_syntax [options]

Arguments	Description
-address="address..."	Email address of the user receiving the push message. If you specify more than one email address, use a space to separate each address in the list. For example: -address="jvc@office.com rmiller@oop.com" At least one email address is required for the Submit command.
-url =url_syntax	The file or web resource that holds the push content. For a file use the file:path syntax. For example: -url=file:saleslist.html where saleslist.html is a file in the current directory. For a web resource, use the following syntax: http://host/<path>
Options include:
-alert	Indicates the message is delivered as an alert instead of a standard push message.
-content-uri=value	The document identifier on the handheld. If not given, the URL is used.
-deliver-after=time	Sets the time the delivery is first attempted. If no time is specified, delivery is started immediately. You can use any of the following values for time: +hh:mm:ss (a time relative to the current time). For example, +17:05:00. mm/dd/yy hh:mm:ss (absolute local time). For example, 12/22/03 07:15:00. yyyy-mm-ddThh:mm:ssZ (absolute UTC time). The T and Z are literal. For example, 2003-11-25T19:40:00Z
-deliver-before=time	Sets the time at which an undelivered message expires. If no time is specified, the server uses a default value. Time values you can specify for the -deliver-before option are the same as for the -deliver-after option.
-destination=[docstore| cache]...	Sets where push content is stored on the handheld. For example: cache (handheld cache directory) docstore (offline document storage) If no destination is specified, offline document storage is assumed. Note: You cannot push contents to Bookmarks. Also, you cannot push Javascript or images to docstore. Pushed Javascript and images are stored in cache, regardless of the destination specified.
-host=host_url	The URL of the push host. If no host URL is specified, http://localhost:5080 is assumed.
-notify=notify_url	A URL that receives result notification messages. If no URL is specified, notifications are not sent.
-priority= "[low|medium|high]"	Specifies a priority level for the message. For example, -priority="high" Higher priority messages are delivered first. If no priority is specified, the message has medium priority.
-push-id=identifier	Specifies the push identifier. If no identifier is specified, a unique push ID is generated automatically. This ID is used to log and track push messages.
-title=doc_title	Sets the document title displayed on handheld. If no title is specified, a Good Intranet-defined value is used.
-type=doc_type	Indicates the type of document being pushed. Values for doc_type include: excel html pdf powerpoint word wml In addition to the specific types listed above, you can also specify other well-known types recognized by the handheld. If no document type is specified, the submit tool will infer the type.

Push Examples

The following is an example of a push message. The commands (with associated arguments and options) are entered on one line (no carriage returns).

jre\bin\java com.good.push.tools.Submit
-address="jjones@mycompany.com" -url=file:C:\service\note.htm

This example sends the note.htm file to jjones@mycompany.com.

jre/bin/java com.good.push.tools.Submit
- address="jjones@mycompany.com marcher@mycompany.com rchen@lglegal.com" -url=file:local/alerts/help.wml -alert -title="Urgent!"

This example sends the file:local/alerts/help.wml file to three recipients (jjones@mycompany.com marcher@mycompany.com rchen@lglegal.com). The message is sent as an alert with an Urgent! title.

Canceling Push Messages

The Cancel command cancels a specified push message. You can cancel the message for all recipients or for one or more specified email addresses.

To cancel a push message:

1. Determine the push ID of the message you want to cancel.
2. Use the following command to cancel the message:

You can enter the command directly on a command line or include it in a script.

jre/bin/java com.good.push.tools.Cancel -push-id=identifier [options]

Argument	Description
-push-id=identifier	The unique identifier of the push message you want to cancel. This argument is required.
Options include:
-host=host_url	The URL of the push host sending the message. If no host URL is specified, http://localhost:5080 is assumed.
-address="address..."	Email address of the user or users whose message should be cancelled. If you specify more than one email address, use a space to separate each address in the list. For example: -address="jvc@office.com rmiller@oop.com" If no address is specified, the message is cancelled for all recipients.

Cancel Examples

The following are some examples of cancelling push messages. Commands (with associated arguments and options) should be entered on one line (no carriage returns).

This example cancels all deliveries of a pushed message:

jre\bin\java com.good.push.tools.Cancel -push-id=note.576

This example cancels a pushed message for two recipients.

jre\bin\java com.good.push.tools.Cancel -push-id=servicenote.87
-address="jchen@company.com mhoft@sct.org"

Checking Push Status

The Status command queries the push server for the status of a particular push message. You can check message status for all recipients or for one or more specified email addresses.

To check the status of a pushed message:

1. Determine the push ID of the message whose status you want to check.
2. Use the following command to check message status:

You can enter the command directly on a command line or include it in a script.

jre\bin\java com.good.push.tools.Status -push-id=identifier [options

Argument	Description
-push-id=identifier	The unique identifier of the push message you want to check for status. This argument is required.
Options include:
-host=host_url	The URL of the push host that sent the message. If no host URL is specified, http://localhost:5080 is assumed.
-address="address..."	Email address of the user or users whose message status should be checked. If you specify more than one email address, use a space to separate each address in the list. For example: -address="jvc@office.com rmiller@oop.com" If no address is specified, message status is checked for all recipients.

]

When you request push status, a message similar to the following appears in the command window:

Status Response from server http://localhost:5080
Push Id : pubs.483
Address : jvc@office.com
Code : 1001
State : pending
Desc : Request has been accepted for processing
Event Time :
Address : rmiller@oop.com
Code : 1000
State : delivered
Desc : Request succeeded
Event Time : 2006-03-27T00:00:27Z
...

The Code field in the status contains a code value for the server's response to the push message as sent by the push initiator. For example:

Push Status Codes

Code	Description
1000	The request succeeded.
1001	Push submission accepted for processing.
2000	Syntax error.
2001	Push submission refused.
2002	Address error.
2003	Address not found.
2007	Duplicate push ID.
3000	Server cannot process the push message because of an internal error.

Status Examples

This example gives the status of all deliverables in a push message ServiceNote.457:

jre/bin/java com.good.push.tools.Status -push-id=ServiceNote.457

Generating Push Reports

In addition to getting push status for individual messages, you can also generate a push report. You can generate a report on:

• All push messages in the database.
• Push messages sent to specific email addresses.
• Push messages with specific content IDs.
• Push messages in specific states.
• Push messages with specific push IDs.
• Use the following command to generate a push report.

You can enter the command directly on a command line or include it in a script.

jre\bin\java com.good.push.tools.Report [options]

Arguments	Description
Options you can use with Report include:
-address="address..."	The report covers push messages for the email addresses specified. If you specify more than one email address, use a space to separate each address in the list. For example: -address="jvc@office.com rmiller@oop.com"
-content-uri="uri..."	The report covers push messages that contain the specified content URIs. If you specify more than one URI, use a space to separate each.
-delivery-state ="state..."	The report covers push messages that have the specified delivery states (for example, expired). If you specify more than one delivery state, use a space to separate each.
-push-id= "identifier..."	The report covers messages with the specified push IDs. If you specify more than one identifier, use a space to separate each.
-dateformat=format	Sets the time format used in the report. Time format options are local or GMT (Greenwich Mean Time). The default is local.
-dbdir	Specifies the push database directory. By default, this directory is install_dir/dbdir/push.

You must invoke the Report command from the Good Intranet Server installation directory or use a -dbdir option to specify the directory where the push database resides (by default this directory is install_dir/dbdir/push).

Important: The low-level push subsystem has a different history than the Push user interface that is available through the Good Intranet Server Console. The Push user interface includes a configurable history, while the Push subsystem removes push messages once they have been delivered and the user has been notified. This means that push messages successfully sent through the Push user interface could be unavailable to the Push reporting tool even though the Push user interface in the Server Console database still has a record of it.

Report Output

Push reports are supplied in XML format and include the push messages that meet the selection criteria specified by Report command options. The following is an example of a push report:

Monitoring Notifications

You can use the Listen command to monitor and display result-notification messages sent by the push server. This command is useful for real-time tracking of changes in message status (for example, delivered or expired).

To monitor notifications:

1. When you use the Submit command to send a pushed message, make sure you include the -notify option as part of the command. For example, use -notify=http://localhost:8081.
2. Use the following command to monitor messages:

Note: You can enter the command directly on a command line or include it in a script.

jre/bin/java com.good.push.tools.Listen [-localport=port_number ]

Argument	Description
-localport=port_number	The port number to listen for result notification messages sent by the push server. The default port number is 8081.