2 Use cases

This chapter includes the following sections:

• Implementing the Save to Topic features

• Save to Topic link

• Save to Topic dialog box

• Save to topic with topic templates

• Save to topic and work teams

• Browse work teams

• Saving attachments

• Viewing topics

Implementing the Save to Topic features

Using the Topics tab in Empirica Signal, an end user can create, display, edit, and move topics through a workflow. Topics can have attachments such as files, graphs, or tables. Topics can also contain one or more actions which can also have attachments.

A topic workflow configuration contains all attributes of topics. Topics are associated with work teams which are sets of users with permissions to view, edit, or save an attachment to a topic. An Empirica Signal administrator defines topic workflow configurations and configures work teams and their permissions.

Your proprietary application can use the Topics web service to display the Save to Topic link and dialog boxes for a user of your application to attach tables, graphs, or files to topics and/or actions.

The use cases in this chapter describe a sample implementation by Empirica Signal of the Save to Topic features and associated web services calls. You can integrate with Save to Topics in your user interface in a way that is appropriate for your proprietary application.

Save to Topic link

Your application can incorporate a Save to Topic link into its pages, similar to how Empirica Signal includes the link above the Data Mining Results Table. If the user clicks the Save to Topic link, the application displays a dialog box and calls the Topics web service. The Topics web service initializes the values and saves an attachment containing the application's data to the specified topic or action.

The following example (Figure 2-1) shows integration points of the Empirica Signal application with Empirica Topics. You can add the Save to Topic link to any page in your application with graphs or tables, or with pages that can be rendered as a file. For example, you can render the contents of a page as a PDF file, and save the PDF file to a topic.

Figure 2-1 Save to Topic link in the Empirica Signal Data Mining Results Table

Topics methods

To implement the Save to Topic link, your application invokes the getUserInfo method. Your application should display the Save to Topic link conditionally, based on the user's permissions. The link should appear only if the user has the appropriate work team permissions.

TopicsUserInfo.getUserInfo().isCanSavetoTopic()

The user must have the same username in your application and in Empirica Topics. TopicsUserInfo.getUserInfo() gives a TopicsServiceException if the username from your application is not found.

Save to Topic dialog box

When the user clicks Save to Topic, the Save to Topic dialog box appears. In the Save to Topic dialog box, the user can save to an existing topic or action, or to a new topic.

Your application should create a Save to Topic dialog box. This page should have similar options to the example (Figure 2-2) and can vary based on your application's design.

Figure 2-2 Save to Topic dialog box in Empirica Signal

To save to a topic or action, the user can enter the attachment name, and select an existing topic from the Add to existing topic drop-down list or create a new topic. If an existing topic is selected, the Action name drop-down list is populated with the actions for that topic. The user can save an attachment to a topic or to an action in the topic.

If the user selects the Create new topic option, a new topic name is required and the user either selects an existing project or a new project. Projects are used to categorize a topic and are optional. The user can select Unassigned from the drop-down list if there is no project. The project Unassigned has ID 0. To create a topic, the user must have the permission to create topics.

Topics methods

Your application invokes the following Topics methods to render the Save to Topic dialog box:

• getUserInfo—Gets the user privileges. The method returns the TopicsUserInfo value object which contains the field CanSaveToNewTopic. If this field is false, you can disable the section for creating topics.

• getTopicContexts—Gets all topics to which the user can save an attachment and populates the existing topics drop-down list.

  
  

  Note: Empirica applications remember the most recent topic when the user saves an attachment. This topic becomes the default topic since users often save additional attachments to the most recent topic. You may design your application to remember the most recent topic.

  
  

• getActionContexts—Gets associated actions using the user's selected existing topic.

  
  

  Note: Empirica applications remember the most recent saved action when the user saves an attachment. This action becomes the default action since users often save additional attachments to the most recent action. You can design your application to remember the last saved action.

  
  

• getProjects—Gets a list of project names associated with your topics. This method is used when creating a topic.

  
  

  Note: Empirica applications remember the most recent project when the user saves an attachment to a new topic. This project becomes the default project for new topics since users sometimes create additional topics within the most recent project. When Empirica applications populate the project drop-down list, they combine the project names returned from the Topics web service with projects from other areas of the application. In this way, users can associate new topics with projects across the application. If your application categorizes objects by name, you can design your application to aggregate project names from topics with other names from your application and thus include all these category names in the project drop-down list. If you specify a project name that does not already exist, the project name is saved as a new project when the topic attachment is saved. You can design your application to remember the most recent project when new topics are created.

  
  

Select Topic dialog box

From the Save to Topic dialog box, the user can browse for existing topics. From the Browse link, the Select Topic dialog box appears where the user can select a topic or can view all properties for available topics.

The example Select Topic dialog box from Empirica Signal can include filter fields to limit the topics that appear in the Select Topic table. When the user selects a topic and clicks OK, the topic appears in the Topic name field of the Save to Topic dialog box.

Your application should create a Select Topic dialog similar to the example (Figure 2-3).

Figure 2-3 Select Topic dialog box in Empirica Signal

Topics methods

Your application invokes the following Topics methods to render the Select Topic dialog box:

• getFieldMetadata—Gets the topic field definitions that are used to populate the column headers in the Select Topic table.

• getFieldValues—Gets the topic field values to populate the rows in the Select Topic table.

• getFilters—Gets topic field definitions and values for topic fields that can be used as filters. An administrator can designate topic fields as filters. These fields can be displayed in this dialog so that a user can limit the list of topics based on the filters.

  
  

  Note: For the above calls, set the FieldContext parameter for the web service call to FieldContext.TOPICS.

  
  

Save to topic with topic templates

If topic templates have been created by an Empirica Topics administrator, and they are visible to a work team to which the user belongs, then the Topic template drop-down list should appear in the Save to Topic dialog box.

If the user selects a topic template from the Topic template drop-down list when creating a new topic, the new topic is populated with the following from the template:

• Topic field values for the initial topic state

• Actions and their field values for the initial action state

If the user does not select a template from the Topic template drop-down list when creating a new topic, none of the fields of the new topic will have pre-defined values and no actions will be created automatically for the topic.

Figure 2-4 Save to Topic dialog box in Empirica Signal when topic templates are available to the user

Topics methods

Your application invokes the following Topics method to render the Topic template drop-down list:

• getTopicTemplateContexts—Gets the topic templates visible to at least one work team to which the user belongs.

Save to topic and work teams

An Empirica Topics administrator can configure a topic workflow configuration such that the topics are visible to one of the following:

• One and only one work team

  or

• Zero, one, or more work teams

If a topic workflow configuration is set to allow a topic to be visible to one and only one work team, the user must select a work team when creating a new topic from within your application. A Visible to work team drop-down list appears in the Save to Topic dialog box when creating new topics.

If a topic workflow configuration is set to allow a topic to be visible to Zero, one, or more work teams, then no Visible to work team drop-down list should appear. A new topic is private to the user who created it or to a superuser. Either of these users can edit the topic from within the Empirica Topics application and publish it by assigning it to one or more work teams.

Figure 2-5 Save to Topic dialog box in Empirica Signal configured for one and only one work team

Topics methods

Your application invokes the following Topics method to render the Visible to work team drop-down list:

• getWorkteamContexts—Gets the work teams based on the user's work team permissions.

Browse work teams

In the Save to Topic dialog box, users can browse work teams. The user clicks Browse to navigate to the Browse Work Teams dialog box (Figure 2-6) and can select a work team. When the user selects a work team and clicks OK, the work team appears in the Visible to work team drop-down list.

Figure 2-6 Browse Work Teams dialog box in Empirica Signal

Topics methods

Your application invokes the following Topics method to render the Browse Work Teams dialog box:

• getFieldMetadata—Gets the work team field definitions that are used to populate the work team column headers in the browse work team table.

• getFieldValues—Gets the work team field values that are used to populate the work team rows in the browse work team table.

• getFilters—Gets work team field definitions and values for work team fields that can be filtered. An administrator can designate work team fields as filters. These fields are displayed in this dialog so that a user can limit the list of work teams based on the filters.

  
  

  Note: For all the above calls, set the FieldContext parameter of the method to FieldContext.WORKTEAMS.

  
  

Saving attachments

In the Save to Topic dialog box, if the user clicks OK, the attachment is saved to the specified topic or action.

Topics methods

Your application invokes the following Topics methods to save the attachment when the user clicks OK in the Save to Topic dialog box:

• attachTopic—Attaches to an existing topic.

• attachAction—Attaches to an existing action.

• attachNewTopic—Creates a new topic and adds the attachment to it.

Streaming attachments

If your application uses Java, use the JAX-WS infrastructure and DataHandler to stream the data to the topics server.

If your application uses .NET, first call the Topics service API streamFileAttachment(), and then call one of the three Topics web service calls to attach the file to a topic or an action.

Viewing topics

The Topics page shows a table of all the topics that are accessible by the user. For example, the user can edit the first topic Acetaminophen using the action menu in the first column of the table (Figure 2-7).

In Empirica Topics, a user can:

• View or edit topics and actions.

• Add attachments such as files and URLs.

• View attachments added using the Save to Topic interface.

• View the source information associated with an attachment.

• Change the topic state to move the topic through the workflow.

Figure 2-7 Topics tab in Empirica Signal

From Edit Topic, the user can view attachments for a topic. If the user mouses over the attachment name, a tooltip is displayed with additional information about the attachment.

Figure 2-8 Edit Topic and Attachment table in Empirica Signal

If the user selects View Source Details from the action menu for the attachment, the source details are displayed in a pop-up window. This window includes the topic name, attachment name, and source at the top of the window.

Figure 2-9 View Source Details in Empirica Signal

To view the attachment, the user selects View from the action menu in the Topic Attachments table. If the attachment is of type TABLE and there are notes associated with the table, a Show Notes link is displayed above the table.

For TABLE type attachments, you send XML with the metadata and data for the table. For more information, see .

Figure 2-10 Attachment—View

The Figure 2-11 shows the attachment after the Show Notes link is selected.

Figure 2-11 Attachment—View and Show Notes