# Using the Administration Console

# Working with ECSpecs

You use ECSpec data objects to tell the Edge Server what information you want from readers, and how you want that reader information reported.

The following sections describe what you can do with ECSpecs:

- Working with ECSpecs in the Administration Console
- Displaying ECSpecs
- Testing ECSpecs Using Activate Once
- Suspending ECSpecs
- Unsuspending ECSpecs
- Deleting ECSpecs
- Viewing ECSpec Subscribers
- Creating and Removing Subscribers
- Editing Subscribers
- Using the ECSpec Editor

## Working with ECSpecs in the Administration Console

Although ECSpec objects can be quite complex, the Administration Console provides an easy way to create and activate ECSpec objects, view the resulting reports, and modify your ECSpec design to meet the needs of the application you are developing.

Using the Administration Console, you can:

- Specify what data you want in a given report.
- Specify where to deliver the report; for example, an HTTP post to a Web address, to a file on your system, or to the Edge Server Console.
- Activate an ECSpec once and view the results.
- Examine the report to determine whether you are getting the information you want.
- Repeat these steps until you are satisfied with the results, then export your ECSpec information for programmatic integration into a production system.

The details of ECSpec objects are covered in Programming with the ALE and ALEPC APIs.

## Displaying ECSpecs

To display ECSpecs:

1. In the left pane of the Console, expand an Edge Server node.
2. Under that Edge Server, select ECSpecs.

The ECSpecs currently defined for this Edge Server are listed in the ECSpecs pane on the upper right.

Table 3-1 describes the ECSpec status information.

Table 3-1 ECSpec Status Information
Column | Description
--- | ---
Name | The name of an ECSpec. You assign this name when you create the ECSpec.
Activation Count | An ECSpec is "activated" each time the start condition is met. This field shows how many times this ECSpec has been activated since its creation.
Last Activated | Last time this ECSpec was activated.
Last Reported | Last time this ECSpec generated a report. Not every ECSpec activation produces a report.
Subscriber Count | Number of subscribers associated with this ECSpec. If the ECSpec has been suspended, a (Suspended) notation appears next to the number of subscribers.

The data for the Name field is taken from the ECSpec object, while the other field data are taken from the ECSpecInfo object. For more information on these objects, see Reading Tags Using the ALE API in Programming with the ALE and ALEPC APIs.

Using the ECSpecs page, you can:

- Add, edit, and view ECSpecs. See Using the ECSpec Editor.
- Work with ECSpecs, including suspending, unsuspending, testing (via "Activate Once"), deleting, and showing subscribers.
- Add, remove, and edit subscribers associated with ECSpecs.

## Testing ECSpecs Using Activate Once

To generate a test report for an ECSpec:

1. In the left pane of the Console, expand an Edge Server node and select ECSpecs.
2. In the ECSpecs pane, select the ECSpec.
3. Click Activate Once.

A Report window displays the XML ECSpec report data from the Edge Server.

A report appears after the ECSpec has completed one activation (for example, the Start and Stop conditions have been met). If the report does not appear quickly, a progress dialog appears. You can cancel the report from this dialog, if desired.

Note: | Activating an ECSpec turns on any readers used by that ECSpec.

The Report window contains menu options to export the report to a file (File > Export), close the window (File > Close), and access Help (Help > EC Report Help).

## Suspending ECSpecs

To suspend an ECSpec:

1. In the left pane of the Console, expand an Edge Server node and select ECSpecs.
2. In the ECSpecs pane, select the ECSpec.
3. Click Suspend.

While the ECSpec is suspended, no information is sent to any of the subscribers associated with that ECSpec. The Subscriber Count column in the ECSpecs pane displays a parenthetical notation if the ECSpec is suspended.

Note: | Suspending an ECSpec may turn off any readers used only by that ECSpec.

## Unsuspending ECSpecs

To unsuspend an ECSpec:

1. In the left pane of the Console, expand an Edge Server node and select ECSpecs.
2. In the ECSpecs pane, select the ECSpec.
3. Click Unsuspend.

The ECSpec resumes sending information to subscribers, and the notation is removed from the Subscriber Count column in the ECSpecs pane.

Note: | Unsuspending an ECSpec turns on any readers used by that ECSpec when the Start condition is met.

## Deleting ECSpecs

To delete an ECSpec:

1. In the left pane of the Console, expand an Edge Server node and select ECSpecs.
2. In the ECSpecs pane, select the ECSpec.
3. Click Delete.

The ECSpec, all its reports, and all subscribers associated with that ECSpec are removed.

## Viewing ECSpec Subscribers

To show subscribers for a given ECSpec:

1. In the left pane of the Console, expand an Edge Server node and select ECSpecs.
2. In the ECSpecs pane, select the ECSpec.

A list of subscribers (destinations for ECSpec report information) and associated status information appears in the bottom Subscribers pane.

Table 3-2 describes the ECSpec subscriber status information.

Table 3-2 ECSpec Subscriber Status Information
Column | Description
--- | ---
URI | URI for this subscriber.
Last Succeeded | Last time the Edge Server succeeded in sending a report to this subscriber.
Consecutive Failures | Number of consecutive times the Edge Server failed in its attempts to send a report to this subscriber.

The URI field is taken from the ECSubscription object, while the other fields are taken from the ECSubscriptionInfo object. For more information on these objects, see Reading Tags Using the ALE API in Programming with the ALE and ALEPC APIs.

## Creating and Removing Subscribers

To create a new subscriber and associate it with the selected ECSpec:

1. In the left pane of the Console, expand an Edge Server node and select ECSpecs.
2. In the ECSpecs pane, select an ECSpec.
3. In the Subscribers pane, click New.
4. On the Subscriber page, select a subscriber type from the drop-down list.

The subscriber type determines what other fields appear on the page.

5. Fill in a destination for the report information to be sent to this subscriber.

Table 3-3 describes the report destinations for the various subscriber types.

Table 3-3 Subscriber Type Report Destinations
Subscriber Type | Destination Prompt | Description
--- | --- | ---
XML on Edge Server Console | "Heading" | Enter a text comment to write the report to the Console in XML, preceded by the comment entered in the Heading field.
XML via HTTP POST | "http://" | Enter a URL to which to deliver the report using HTTP POST. Format: `host:port/remainder-of-URL` (The colon and port number may be omitted; the port number defaults to 80.)
XML via JMS Message | "TOPIC" or "QUEUE" | Enter the name of the topic that the JMS notification driver will publish to, or the name of the queue that the JMS notification driver will add to. The topic or queue entered must exist in the JMS server. See Table 3-4 for JMS subscriber properties.
XML File on Edge Server | "Directory or File" | Enter a directory path or file name to which to deliver the report by writing to the specified file.
XML via TCP/IP | "Host" and "Port" | Enter a host name and port number to which to deliver the report using a client TCP socket.
Workflow Module | "Module" | Enter a destination workflow module name to which to deliver the report.
Other | "URI" | Enter a URI to which to deliver the report.

6. (JMS only) Fill in values for the JMS subscriber-specific properties shown in Table 3-4.

Note: | To configure SAF JMS notifications, see Configuring the Edge Server To Use Client-side SAF.

Table 3-4 Subscriber Page (JMS Options)
Name | Description
--- | ---
Connection Factory | JNDI name of the connection factory (from the JMS server) for obtaining a topic connection or a queue connection. Use a topic connection factory name when you publish to a topic. Use a queue connection factory name when you add to a queue.
Provider URL | Optional. URL for the JNDI Naming service.
User | Optional. User name used to create a JMS topic or queue connection.
Password | Optional. Password used to create a JMS topic or queue connection.
Security Principal | Optional. Security principal associated with the JNDI Naming Service.
Authentication | Optional. Authentication string associated with the security principal.
Credential | Optional. Security credential associated with the security principal.
Naming Service Message Properties | Optional. These are added to the `javax.naming.Context` environment when one is constructed, in order to access a naming service to perform the necessary JNDI lookups. Name is the naming service message property name. Names are prefixed with `jndi:` Value is the string value.
Note: | In general, the properties in a naming properties file are considered default values, and can be overridden by a notification subscription URI (by adding the equivalent property to the notification URI as a query parameter). However, when configuring a SAF client, you cannot override naming properties by using a notification subscription URI. SAF only uses the properties in the naming properties file.
JMS Message Properties | Optional. These are added to the `javax.jms.TextMessage as String` properties. Name is the text message property name. Value is the string value.

7. Fill in values for the Failure Action section.

If the delivery of a report to a subscriber fails on consecutive tries, the Edge Server can automatically unsubscribe that subscriber. The Failure Action section defines the conditions under which that can occur. You can use the default failure action (Use defaults) or override it (Override defaults).

If you chose to override the defaults, specify one or both failure actions by clicking the check box next to the action - unsubscribe after N consecutive failures, or unsubscribe after N milliseconds of consecutive failures. You also need to enter a reasonable number for each action selected.

8. Click Subscribe to save your changes and associate the new subscription with the ECSpec.

To remove a subscriber from an ECSpec:

1. In the ECSpecs pane, select an ECSpec.
2. In the Subscribers pane, select a subscriber.
3. Click Delete.

## Editing Subscribers

To edit a subscriber:

1. In the left pane of the Console, expand an Edge Server node and select ECSpecs.
2. In the ECSpecs pane, select an ECSpec.
3. In the Subscribers pane, select a subscriber.
4. Click Edit.
5. On the Subscriber page, make any desired changes and click Save.

Note: | When the new subscriber is saved, the original subscriber is unsubscribed and the changed subscriber is saved. If the save fails, the original subscriber remains unsubscribed (removed).

## Using the ECSpec Editor

Use the ECSpec Editor to:

- Add, edit, view, and deploy ECSpecs.
- Add and edit ECSpec reports, report filters, report groups, and user memory regions.
- Test an ECSpec.
- Import an ECSpec.
- Export an ECSpec to an XML file.

### Displaying the ECSpec Editor

To display the ECSpec Editor:

1. In the left pane of the Console, expand an Edge Server node and select ECSpecs.
2. In the ECSpecs pane, select an ECSpec and click Edit.

The ECSpec Editor is displayed with four main menus:

- File Menu
- Tools Menu
- View Menu
- Help Menu

#### File Menu

Table 3-5 describes the ECSpec Editor File menu options.

Table 3-5 File Menu Options
Name | Description
--- | ---
Deploy | Deploys this ECSpec using the current name (equivalent to `redefine` in the ALE API). This menu item is enabled if you have unsaved changes to a previously defined ECSpec.
Deploy As... | Deploys this ECSpec using another name. You are prompted for the name. This item is equivalent to `define` in the ALE API.
Revert | Resets the ECSpec being edited to the last deployed version, and discards any recent changes made using the ECSpec Editor. If you have imported an ECSpec and have not yet deployed it, reset the ECSpec being edited to the version you imported.
Export | Exports this ECSpec to an XML file.
Close | Closes the ECSpec Editor.

#### Tools Menu

Table 3-6 describes the ECSpec Editor Tools menu options.

Table 3-6 Tools Menu Options
Name | Description
--- | ---
Test | Tests this ECSpec. See Testing ECSpecs.

#### View Menu

Table 3-7 describes the ECSpec Editor View menu options.

Table 3-7 View Menu Options
Name | Description
--- | ---
ECSpec Editor | View the ECSpec in the ECSpec Editor. Use the ECSpec Editor to modify and deploy your ECSpecs.
As XML | View the ECSpec in XML format. Use the ECSpec Editor to make further changes.
As Text | View the ECSpec in text format. Use the ECSpec Editor to make further changes.

#### Help Menu

Table 3-8 describes the ECSpec Editor Help menu options.

Table 3-8 Help Menu Options
Name | Description
--- | ---
ECSpec Help... | Displays a link to the Administration Console Help.

### Creating and Deploying ECSpecs

Note: | You must create at least one ECSpec Report before deploying an ECSpec. See Creating ECSpec Reports.

To create and deploy an ECSpec:

1. In the left pane of the Console, expand an Edge Server node and select ECSpecs.
2. In the ECSpecs pane, click New.
3. In the ECSpec Editor, move one or more logical readers from the Available list to the Selected list using the arrows between the lists.
4. Add a Start condition and one or more Stop conditions to the ECSpec, using the controls in the Start and Stop sections in the ECSpec Editor.

When the ECSpec has an active subscriber, the readers specified in the ECSpec start reading tags when the start condition is satisfied, and stop reading tags when any of the stop conditions are satisfied.

Table 3-9 describes ECSpec start conditions and Table 3-10 describes ECSpec stop conditions.

Table 3-9 ECSpec Start Conditions
Start Condition | Description
--- | ---
Continuous | Start the next event cycle as soon as the previous event cycle ends.
Repeat Period (Milliseconds) | Start the next event cycle after a specified amount of time has elapsed from the start of the previous event cycle.
Trigger URI | Start the event cycle when a trigger is received.

Table 3-10 ECSpec Stop Conditions
Stop Condition | Description
--- | ---
Duration (Milliseconds) | Stop reading tags after the stated number of milliseconds.
Duration (Read Cycles) | Stop reading tags after the stated number of read cycles.
Stable Set Interval (Milliseconds) | Stop reading tags after the stated number of milliseconds have elapsed with no new tags seen.
Stable Set Interval (Read Cycles) | Stop reading tags after the stated number of read cycles have elapsed with no new tags seen.
Minimum Stable Count | Stop reading tags after the stated number of tags have been seen and, for each report, the stated number of tags are included in that report.
Trigger URI | Stop reading tags when a trigger condition is received.

5. Enter application-specific data in the Application Data field, if any.

Data entered here is copied to every report generated from this ECSpec.

6. Add at least one report to the ECSpec: select the Reports node in the left pane and click the New Report button in the right pane.

See Creating ECSpec Reports for more information.

7. Deploy the finished ECSpec by clicking the Deploy As button on the ECSpec Editor toolbar, filling in a name for the ECSpec when prompted, and clicking OK to save your changes.

You may want to test the ECSpec before deploying. See Testing ECSpecs.

### Importing ECSpecs

To import an ECSpec:

1. In the left pane of the Console, expand an Edge Server node and select ECSpecs.
2. In the ECSpecs pane, click Import.
3. Select the ECSpec file to import and click Open.

The ECSpec Editor displays the imported ECSpec.

4. Edit the ECSpec, if desired, and add, remove, or edit its report information.
5. Deploy the ECSpec by clicking the Deploy As button on the ECSpec Editor toolbar (or by selecting File > Deploy As), filling in a name for the ECSpec when prompted, and clicking OK.

You may want to test the ECSpec before deploying. See Testing ECSpecs.

### Editing ECSpecs

To edit an existing ECSpec:

1. In the left pane of the Console, expand an Edge Server node and select ECSpecs.
2. In the ECSpecs pane, select an ECSpec.
3. Click Edit.

The ECSpec Editor displays the ECSpec.

4. Edit the ECSpec, and add, remove or edit reports and filter information.
5. Deploy the finished ECSpec by clicking the Deploy button on the ECSpec Editor toolbar (or by selecting File > Deploy) and clicking OK.

You may want to test the ECSpec before deploying. See Testing ECSpecs.

### Testing ECSpecs

To test an ECSpec:

1. In the left pane of the Console, expand an Edge Server node and select ECSpecs.
2. In the ECSpecs pane, select an ECSpec.
3. Click Edit.
4. Click the Test button on the ECSpec Editor toolbar (or select Tools > Test) to generate a test report.

If the test is successful, a Report window displays XML report data from the Edge Server after the ECSpec completes one activation (for example, the Start and Stop conditions are met).

If the report does not appear quickly, a progress dialog appears. You can cancel the report from this dialog, if desired.

Note: | Testing an ECSpec turns on any readers used by that ECSpec.

The Report window contains menu options to export the report to a file (File > Export), close the window (File > Close), and access Help (Help > EC Report Help).

### Viewing ECSpecs as XML or Text

To view an ECSpec as XML or text:

1. In the left pane of the Console, expand an Edge Server node and select ECSpecs.
2. In the ECSpecs pane, select an ECSpec.
3. Click Edit.

The ECSpec Editor displays the ECSpec.

4. Select View > As XML or View > As Text.

The ECSpec Editor displays the ECSpec in text or XML format.

### Exporting ECSpecs

To export an ECSpec to an XML file:

1. In the left pane of the Console, expand an Edge Server node and select ECSpecs.
2. In the ECSpecs pane, select an ECSpec.
3. Click Edit.

The ECSpec Editor displays the ECSpec.

4. Click the Export button on the toolbar (or select File > Export) to export the ECSpec to an XML file.
5. Specify a file name and location, and click Save.