3 API

This chapter includes the following sections that describe each topic service method call in detail:

• API summary

• Common value objects

• Methods

• Exceptions

• Upload files for .NET

API summary

The API includes the following topic service methods that retrieve information about topics or actions, or save to a topic or action. All input is validated, including checks to verify that a user has permission to save to topic or action. Any data that is retrieved is based on the user's work team permissions and topic workflow configuration.

Table 3-1 Topics Service API summary.

Operation	Method Name	Description
Get a list of topics	getTopicContexts	Retrieves topic names and IDs.
Get a list of actions	getActionContexts	Retrieves action names and IDs for a topic.
Get a list of work teams	getWorkteamContexts	Retrieves work team names and IDs.
Get a list of topic templates	getTopicTemplateContexts	Retrieves topic template names and IDs.
Attach to an existing topic	attachTopic	Creates an attachment to an existing topic.
Attach to a new topic	attachNewTopic	Creates an attachment to a new topic.
Attach to an action	attachAction	Creates an attachment to an existing action.
Get field metadata	getFieldMetadata	Retrieves field properties for topics, topic templates, or work teams.
Get field values	getFieldValues	Retrieves field values for topics, topic templates, or work teams.
Get filters	getFilters	Retrieves fields defined as filters and their values for topics, topic templates, or work teams.
Get a list of projects	getProjects	Retrieves projects used by the user's topics.
Get user info	getUserInfo	Retrieves topic permissions for the user such as, can the user save to a topic.
Get topics service properties	getTopicsServiceProperties	Retrieves the topics service version and other topics service properties. This can be used to determine whether the topics service is available and is (or has) a version compatible with your version of the API.

Common value objects

Topics service methods contain value objects that are passed as arguments or returned from service calls. This document describes the member variables for each value object. If you are importing the WSDL with Java, the value objects have protected member variables and your application will access the variables through public getters and setters that are generated from the WSDL. These fields are available in the getFieldName and setFieldName form. If you are importing the WSDL with .NET, the member variables are public rather than having getters and setters.

TopicsServiceContext value object

Most methods have a TopicsServiceContext value object passed as a parameter. This value object contains context information to process a request. The username field is required. You can also set optional parameters.

startRow and chunkSize—To page the resulting data by making multiple calls to the method with a starting row number and the number of rows to return with each call.

Table 3-2 TopicsServiceContext optional parameters.

Field name	Parameter type	Description
applicationName	Input	Name of your proprietary application. This field is appended to the source metadata for an attachment. For example, if the AttachmentInput.source field is specified as Results, the source is modified to be Results - My Application Name. When viewing attachments in Empirica Topics, this field enables a user to distinguish attachments from a variety of applications.
applicationInstance	Input	Reserved for future use.
version	Input	Version of the Topics API that you are using. Empirica Signal Release 8.0 contains version 2 of the Empirica Topics API as described in this document. If your Topics API version is greater than the Empirica Topics server version, a TopicsServiceException is thrown.
sortOrder	Input	List of columns on which to sort data and the sort order for each column. This field applies to only the getFieldValues method and is ignored for any other methods. If this field is not specified, a default sort order is used.
filter	Input	List of columns on which to filter data and the filter value to match on. This field applies to only the getFieldValues method and is ignored for any other methods. If this field is not specified, the data is returned without any filtering.
startRow	Input	Start row from which to begin retrieving data. If this field is not specified, the default value is 1.
chunkSize	Input	Maximum number of rows returned by the service on any applicable calls. Use this field to page large amounts of data rather than returning everything in one call. If this field is not specified, the default value is 500 rows. The fields chunkSize and startRow apply to the getTopicContexts, getActionContexts, getFieldValues, getWorkteamContexts, and getProjects methods. These fields are ignored for other methods.
nameContainsFilter	Input	Case-insensitive wildcard filter for topic names. This field applies only to the getTopicContexts method and is ignored for any other methods. If specified, this field filters the results to topic names that contain this text.
version	Output	Topics service version of the Empirica Topics server.
maxRows	Output	Maximum number of rows for a table attachment when attaching a TABLE attachment type. This value is determined by a site option, Max number of rows per table allowed in topic attachments, defined on the Empirica Topics server. You can also get this property from the getTopicsServiceProperties method.
numRows	Output	Number of rows that were retrieved by the method. This field is less than or equal to the chunk size.
totalRows	Output	Total number of rows available for the method. You can use this value to display the total number of pages of the result based on the chunk size. This field applies to the getTopicContexts, getActionContexts, getTopicTemplateContexts, getWorkteamContexts, and getFieldMetadata, getFieldValues methods.

class TopicsServiceContext {
  String applicationName;
  String applicationInstance;
  Integer version;
  String username;
  Integer maxRows;
  Integer startRow;
  Integer chunkSize;
  Integer numRows;
  Integer totalRows;
  List<TopicsSortOrder> sortOrder;
  List<TopicsFilter> filter;
  String nameContainsFilter;
}

Methods

This section discusses the Empirica Topics methods in detail.

Get a list of topics

Your application retrieves a list of topics by using the getTopicContexts method, which returns a list of topic contexts with the name and identifier of each topic. This method can be used to populate a drop-down or selection list of existing topics in the Save to Topic dialog box.

The result is alphabetically sorted by name and includes the number of values returned and the total number of values. Optionally, you can set a start row and a chunk size in the TopicsServiceContext value object.

TopicContexts getTopicContexts(TopicsServiceContext serviceContext, 
                               long findTopicId)
throws InvalidArgumentException, TopicsServiceException;

This method returns all topics available to this user. To also search for a particular topic by ID, set the findTopicId parameter to an ID that is greater than or equal to 0.

To limit the results by name, set the TopicsServiceContext.nameContainsFilter field to a string. In this case, the method returns only TopicContexts with topic names that contain that string with a case insensitive search. For example, when you set the nameContainsFilter field to imp, the resulting topic contexts might have results Important Results and Topics imported.

TopicsContexts value object

The getTopicContexts method returns TopicContexts, which has a list of topic IDs and names. TopicContexts extends the value object TopicsServiceContext and has the actual number of rows returned in numRows field and the total number of rows in the totalRows field.

If the findTopicId parameter was set, then the matchingTopicContext field in TopicsContexts contains the matching context or null if it was not found or not set. You can use this field to implement an auto complete field for the existing topic name in the Save to Topic dialog box in your application.

Note: Topic names are not unique.

class TopicContexts extends TopicsServiceResult {
  TopicContext matchingTopicContext;
  List<TopicContext> topicContexts;
}

class TopicsServiceResult {
  TopicsServiceContext topicsServiceContext;
}

class TopicContext {
  long id;
  String name;
}

Get a list of actions

Your application retrieves a list of actions for a topic available to the user by calling the getActionContexts method, which returns a list of action contexts with the action name and ID, and the associated topic ID. The result is sorted by name and includes the number of actions returned and the total number of values. You should add an option in your user interface to not select an action. The Empirica Signal application adds the options --none-- to the top of the drop-down list. Optionally, you can set a start row and a chunk size.

ActionContexts getActionContexts(TopicsServiceContext topicsServiceContext,
                                 long topicId)
throws InvalidArgumentException, TopicsServiceException;

ActionContexts value object

The value object of the getActionContexts method returns a list of ActionContexts with action IDs and names and the associated topic ID.

class ActionContexts extends TopicsServiceResult {
  List<ActionContext> actionContexts;
}

class ActionContext {
  long id;
  String name;
  long topicId;
}

Get a list of work teams

Your application can retrieve a list of work teams by using the getWorkteamContexts method. This method returns a list of work team contexts with the work team name and ID. The result is sorted by name and includes the values returned and the total number of values.

When using Save to Topic with a Topic Workflow Configuration that is set to one and only one work team, this method can be used to populate the list of work teams in the Save to Topic dialog box.

WorkteamContexts getWorkteamContexts (TopicsServiceContext serviceContext)
throws InvalidArgumentException, TopicsServiceException;

WorkteamContexts value object

The getWorkteamContexts method returns WorkteamContexts with a list of work team names and IDs.

class WorkteamContexts extends TopicsServiceResult { 
  List<WorkteamContext> workteamContexts;
}

class WorkteamContext {
  long id;
  String name;
}

Get a list of topic templates

Your application can retrieve a list of topic templates. The topic templates can be used to prepopulate new topic fields and actions.

To get a list of topic templates, call the getTopicTemplateContexts method, which returns a list of topic template contexts with the name and identifier of each topic template. This method can be used to populate a drop-down list or a selection list for the topic template in the Save to Topic dialog box. You should add an option in your user interface to not select a template. The Empirica Signal application adds the options --none-- to the top of the drop-down list.

The result is alphabetically sorted by name and includes the values returned and the total number of values. Optionally, you can set a start row and a chunk size.

TopicTemplateContexts getTopicTemplateContexts(TopicsServiceContext serviceContext)
throws InvalidArgumentException, TopicsServiceException;

TopicTemplateContexts value object

The getTopicTemplateContexts method returns TopicTemplateContexts with a list of topic template IDs and names.

Note: Topic template names are not unique.

class TopicTemplateContexts extends TopicsServiceResult {
  List<TopicTemplateContext> topicTemplateContexts;
}
 
class TopicTemplateContext extends BaseTopicContext {}
 
class BaseTopicContext {
 long id;
 String name;
}

Attach to an existing topic

Your application can create an attachment to an existing topic. The topic argument in the attachTopic method contains the identifier of the topic. Set the id field of the topicContext argument to the ID of the topic to attach to. The attachmentInput argument has the name, extension, attachment type, and optional properties of the attachment. The dataHandler field is a W3C MTOM (Message Transmission Optimization Mechanism) type to stream data.

The attachment types are:

• IMAGE—A ZIP file with a series of JPG, JPEG, PNG, or GIF images, optional *.txt files, and optional notes.txt files. If a text file other than notes*.txt contains a comma-separated list, each item is rendered on a separate line.

• FILE—Any file, such as a PDF file.

• TABLE—An XML representation of a table. For example, a case series table. See for the XML definition.

Typically, your application writes an IMAGE or TABLE attachment to a temporary file, streams the file using the attachTopic, attachNewTopic, or attachAction method, and then deletes the file. A .NET client calls the streamFileAttachment method first, and then calls the attachTopic, attachNewTopic, or attachAction method.

void attachTopic(TopicsServiceContext topicsServiceContext, 
                 TopicContext topicContext, AttachmentInput attachmentInput)
throws InvalidArgumentException, TopicsServiceException

AttachmentInput value object

The attachment input value object includes the following fields:

• name—Required name field.

• description—Optional description.

• source—Required brief name of the source, such as ”Cases”.

• sourceText—Required brief information about the attachment. This text is application-dependent and the field supports HTML tags, such as <br> and <table><tr><td> and font formatting tags. This might contain metadata to display to the user about the attachment such as the number of cases.

  It is displayed in the tooltip for values in the Attachment name column in the Topic or Action Attachments table when viewing or editing a topic. The text is limited to 500 characters by Internet Explorer.

  If the notes field is not specified, then the sourceText is also displayed in the View Source Details dialog box. The dialog box is displayed when the user selects View Source Details for an attachment type.

• type—Required attachment type of IMAGE, FILE, or TABLE. The types NOTE, URL, and SIGNAL are reserved for future use.

• extension—Name of the extension. This is required if the attachment type is FILE. If the type is IMAGE, a ZIP file extension is required and the zip file contains JPG, JPEG, PNG, or GIF images, optional *.txt files with strings such as section headers, and optional notes*.txt files.

• notes—Optional details that contain an encapsulated HTML <table> tag for notes. Notes are more detailed and can be much longer than the sourceText field since they are displayed in a scrollable window and not in a tooltip.

  If specified, the notes field is displayed in the View Source Details dialog box when selecting View Source Details for an attachment in the Topic or Action Attachments table. If the notes field is not specified, then the sourceText field value is displayed in the View Source Details dialog box. This field can be formatted with HTML tags such as formatting as an HTML table and setting the font style for the text.

  The notes field is different from the notes shown by selecting the Show Notes link above a TABLE. The optional notes on a TABLE are part of the XML that is streamed with the attachment. This notes field is also different from the notes in IMAGE attachments, where any notes*.txt files in the IMAGE zip file are always displayed along with image files in the attachment.

• dataHandler—Used by Java clients to stream data. The DataHandler is a MTOM (W3C Message Transmission Optimization Mechanism) for streaming data to transfer large amounts of data. It can be used for large or binary files.

  For .NET, the dataHandler variable is not used and you should call the streamFileAttachment method to stream your attachment.

• guid—Used by .NET clients when streaming data. The guid uniquely identifies the attachment across two method calls, the first to stream the attachment and then the second to attach to a topic or action.

• urlAddress—Reserved for future use.

• data—If the attachment type is FILE, the data field must be specified with a filename including the extension. This field is required for FILE types and is used when creating a PDF of the topic with the attachment. The attachment is displayed as a link in the PDF with the filename from the data field.

class AttachmentInput {
  String name;
  String description;
  String source;
  String sourceText;
  AttachmentType type;
  String extension;
  String notes;
  String data;
  DataHandler dataHandler;
  String guid;
  String urlAddress;
}
 
enum  AttachmentType {
  NOTE, IMAGE, FILE, URL, SIGNAL, TABLE
}

Attach to a new topic

Your application can create an attachment to a new topic. The attachNewTopic method creates an attachment to a new topic. For information about the attachmentInput argument, see Attach to an existing topic.

attachNewTopic method

TopicResult attachNewTopic(TopicsServiceContext topicsServiceContext, 
                           TopicInput topicInput, AttachmentInput attachmentInput)
throws InvalidArgumentException, TopicsServiceException;

TopicInput value object

The TopicInput value object has the required name field for the topic name and the following optional parameters:

• projectName—Name to categorize the topic (required if newProject is true)

• description

• workteams—A list of work team names

• newProject—A boolean set to true to create new project

• templateId—ID for the topic template

Any optional values must be set to null if they are not defined otherwise.

The server creates the topic with a default initial state but no values are set for any topics fields. Topic names are not unique. If a topic is created with the same name as an existing topic, the user might see multiple topics with the same name in the topic drop-down list. A user can display the Select Topic dialog box to distinguish between different topics with the same name by viewing other fields associated with the topic.

If specified, the templateId field should have the ID of the topic template from the user's selection and is available from the TopicTemplateContext. If the user does not select a topic template, set the template ID to null.

If you do choose not to support projects in your user interface or do not display the project drop-down list, then if the user creates a topic, you must set the projectName field to Unassigned.

class TopicInput {
  String name;
  String projectName;
  String description;
  String[] workteams;
  boolean newProject;
  Long templateId;
}

Attach to an action

Your application can create an attachment to an existing action by calling the attachAction method. The action argument contains the identifier of the action. Set the id field of the actionContext argument to the ID of the action to attach to and the topicId field to the topic ID for the action. For information on the attachmentInput argument, see Attach to an existing topic.

void attachAction(TopicsServiceContext topicsServiceContext, 
                  ActionContext  actionContext, AttachmentInput attachmentInput)
throws InvalidArgumentException, TopicsServiceException;

Get field metadata

Your application can retrieve a list of all fields for topics, topic templates, or work teams by calling the getFieldMetadata method. This method can be used to browse topics and choose a topic based on additional information, such as the assigned user, state, or any field, or to browse topic templates or work teams. Set the fieldContext argument to one of the enumeration values of FieldContext: TOPICS, TOPIC_TEMPLATES, or WORKTEAMS. This returns the FieldMetadata value object with a list of field properties.

FieldMetadata getFieldMetadata(TopicsServiceContext topicsServiceContext, 
                               FieldContext fieldContext)
throws InvalidArgumentException, TopicsServiceException;

The FieldContext input parameter is an enumeration for topics, topic templates, or work team values.

enum FieldContext {
  TOPICS, TOPIC_TEMPLATES, WORKTEAMS;
}

FieldMetadata value object

The FieldMetadata value object has a list of metadata of all fields in each topic, topic template, or work team. The metadata includes the field identifier, display label, type, whether the field is required, and whether the field can be presented to the user as a filter.

class FieldMetadata extends TopicsServiceResult {
  List<Field> fields;
}
 
class Field {
  String id;
  String label;
  FieldType type;
  boolean filterable;
  boolean required;
}

The field types are defined in an enumeration as follows. FLOAT is reserved for future use.

enum FieldType {
  STRING, DATE, INTEGER, LONG, FLOAT, PROJECT, STATE
}

Get field values

Your application can retrieve a list of all field values for each topic, topic template, or work team by calling the getFieldValues method. This method can be used to browse topics and choose a topic based on additional information, such as the assigned user, state, or to browse topic templates or work teams. Set the fieldContext argument to one of the enumeration values of FieldContext: TOPICS, TOPIC_TEMPLATES, or WORKTEAMS. This method returns the FieldValues value object with a list of fields.

• For topics, the values reflect topics that are open and can be either viewed or attached to by the user.

• For work teams, the values reflect work teams associated with topics available to the user.

FieldValues getFieldValues(TopicsServiceContext serviceContext, 
                           FieldContext fieldContext)
throws InvalidArgumentException, TopicsServiceException;

The FieldContext input parameter in an enumeration for topics, topic templates, or work team values.

enum FieldContext {
  TOPICS, TOPIC_TEMPLATES, WORKTEAMS
}

FieldValues value object

The FieldValues value class has an ids field, which is an ordered list of identifiers, and a values field, which is a list of arrays of field values associated with the ids.

class FieldValues extends TopicsServiceResult {
  ArrayList<Long> ids; 
  ArrayList<FieldValueArrayGenerated> values;
}
 
class FieldValueArrayGenerated {
  FieldValue[] values;
}

Each FieldValue object has the field type, the name of the field, and a field value depending on the type. STRING types are returned as stringValue fields. INTEGER or LONG types are returned as a longValue fields. DATE types are returned as dateValue fields. The nameIdPair field is used when the type is PROJECT or STATE and returns pairs of the identifier and name for the project or state.

The floatValue field is reserved for future use.

class FieldValue {
  FieldType type;
  String fieldName;
  String stringValue;
  Long longValue;
  Date dateValue;
  NameIdPair nameIdPair;
  Float floatValue;
}
 
class NameIdPair {
  String id;
  String name;
}

Get filters

Your application can retrieve a list of fields that have been set up as filters and their values by calling the getFilters method.

Filters getFilters(TopicsServiceContext topicsServiceContext, 
                   FieldContext fieldContext)
throws InvalidArgumentException, TopicsServiceException;

Filters value object

The Filters object is returned from the getFilters method and is an ordered list of filter field names. You can create a filter drop-down list for each item in the fieldNames list. Set the label of the drop-down list to the String value of the fieldNames list. The Filters object also contains an array of filter values associated with each filter field name with the label which is the text to display in the drop-down list and the value which is the field value associated with that label. The label can be the same as the value.

class Filters extends TopicsServiceResult {
  ArrayList<String> fieldNames; 
  ArrayList<FieldValuePairGenerated> values;
}
 
class FieldValuePairGenerated {
  FieldValuePair[] values;
}
 
class FieldValuePair {
  String label; 
  FieldValue value;
}

Filtering results

An end user might use this method, for example, when looking for topics with a drug name in a custom field.

class TopicsServiceContext {
  …
  List<TopicsSortOrder> sortOrder;
  List<TopicsFilter> filter;
  …
}

After the end user selects one or more filters, set the filter field in the TopicsServiceContext when calling getTopicContexts, getFieldValues, and getProjects. TopicsFilter is a list of filter field names and the selected filter values. The fieldName field must be one of the values in the fieldNames field returned from getFilters and the value must be one of the associated values returned from getFilters.

Sorting results

An end user can sort the topic, topic template, or work team field values. Your application sets TopicsServiceContext.sortOrder field with a list of fields to sort and whether to sort each field in ascending or descending order. The default is ascending order if the order is not specified.

class TopicsServiceContext {
  …
  List<TopicsSortOrder> sortOrder;
  List<TopicsFilter> filter;
  …
}

TopicsSortOrder value object

Set the fieldName field to the name of the topic, topic template, or work team to sort on. Set the sorting order field to SORT_ASC or SORT_DESC. Set the fieldType to STRING for a case insensitive sort of string values. This method applies to only the getFieldValues method.

class TopicsSortOrder {
  String fieldName;
  FieldType fieldType = FieldType.STRING;
  Order order = Order.SORT_ASC;
}

The field types are defined in an enumeration as follows:

enum FieldType { 
  STRING, DATE, INTEGER, LONG, FLOAT, PROJECT, STATE 
}
 
enum Order {
  SORT_ASC, SORT_DESC
}

Get a list of projects

Your application can retrieve a list of existing projects by calling the getProjects method. A project can be optionally specified when creating a topic. This method returns the ProjectList value object that always includes a value called Unassigned with ID 0.

ProjectList getProjects(TopicsServiceContext serviceContext)
throws TopicsServiceException

ProjectList value object

class ProjectList extends TopicsServiceResult {
  List<String> projects;
}

Get user info

Your application can view the topic permissions for a user by calling the getUserInfo method. Your application might hide or disable the Save to Topic link if the user cannot save to Topics.

TopicsUserInfo getUserInfo(TopicsServiceContext topicsServiceContext, 
                           String username)
throws InvalidArgumentException, TopicsServiceException;

TopicsUserInfo value object

The TopicsUserInfo method has the following fields:

• canSavetoTopics—True if a user can save to a topic. If true, your application can display the Save to Topic link.

• canCreateTopic—True if a user can create a topic. If true, your application can enable fields to create a topic in the Save to Topic dialog box.

• canAccessMultipleWorkteams—True if a user can select zero or more work teams for a new topic.

  If true, your application should not display the work team drop-down list in the Save to Topic dialog box.

  If false, then each new topic must be assigned to one work team. Your application must display a work team selector, such as a drop-down list, in the Save to Topic dialog box to assign the new topic to a work team.

• canViewTopics—Reserved for future use.

class TopicsUserInfo extends TopicsServiceResult {
  String username;
  boolean canSaveToTopics;
  boolean canSaveToNewTopic;
  boolean canAccessMultipleWorkteams;
  boolean canViewTopics;
}

Get topics service properties

Your application can retrieve the Topics server version and other properties by calling the getTopicsServiceProperties method.

TopicsServiceProperties getTopicsServiceProperties();

TopicsServiceProperties value object

The getTopicsServiceProperties method returns the TopicsServiceProperties value object with the following fields:

• serverVersion—The version of the topics server. If your API version is greater than the Topics server version, you might experience compatibility issues.

  
  

  Note: Topics services are backward compatible with earlier client versions.

  
  

• attachMaxRows—Defines the maximum number of rows in a TABLE attachment that your application can add. Your application is responsible for truncating the rows in a table to this value before sending it to the server.

• attachMaxMegabytes—Defines the maximum megabytes of any attachment. The topics service throws a TopicsServiceException if your application attempts to add an attachment greater than the attachMaxMegabytes value in megabytes.

class TopicsServiceProperties {
  Integer serverVersion;
  Integer attachMaxRows;
  Integer attachMaxMegabytes;
}

Exceptions

Exceptions are thrown by a method call when the Topics service detects a user error or an internal error.

Topics service methods may throw the following exceptions:

• InvalidArgumentException—Thrown for internal errors if you define invalid information in a field or argument. One example is passing a TopicsServiceContext argument with a value of null. Another example is requesting actions for a topic ID of -5. Topic IDs must be a number greater than or equal to 0.

• TopicsServiceException—Thrown for errors other than InvalidArgumentException. This includes user input errors. Another example is a semantic error such as getting actions contexts for a topic with an ID that does not exist, or for a topic that was deleted or closed.

These exceptions contain an errorCode field that categorizes the exception, a message field with a default message that can be displayed to the user, and a detailedMessage field for logging and diagnostics.

You can either display the default message or create a customized message for a particular error code. For example, if there is a missing topic name for a new topic, the customized message could be The new topic name is required instead of the default message You must enter a new topic name.

TopicsServiceException value object

class TopicsServiceException extends Exception {
  String detailedMessage;
  TopicsServiceErrorCode errorCode;
  String message;
}

Table 3-3 TopicsServiceException error codes.

Error Code	Description
TOPIC_ERROR_INTERNAL	Internal error.
TOPIC_ERROR_NO_SERVICE	Communication error with the topic server.
TOPIC_ERROR_TOPIC_NAME_REQUIRED	attachNewTopic method called with the topicInput parameter name field not set.
TOPIC_ERROR_ATTACHMENT_NAME_REQUIRED	attachTopic, attachNewTopic, or attachAction method called with the attachmentInput parameter name field not set.
TOPIC_ERROR_PROJECT_NAME_REQUIRED	attachNewTopic method called with topicInput parameternewProject field set but projectName field not set.
TOPIC_ERROR_TOPIC_CLOSED	attachTopic method called with the topicContext parameter field id set to a closed topic.
TOPIC_ERROR_ACTION_CLOSED	attachAction method called with the actionContext parameter field id set to a closed action.
TOPIC_ERROR_TOPIC_DELETED	attachTopic method called with the topicContext parameter field id set to a deleted topic.
TOPIC_ERROR_ACTION_DELETED	attachAction method called with the actionContext parameter field id set to a deleted action.
TOPIC_ERROR_UNAVAILABLE_TOPIC	attachTopic method called with the topicContext parameter field id set to a topic that is not available.
TOPIC_ERROR_UNKNOWN_ACTION	attachAction method called with the actionContext parameter field id set to an action that is not available.
TOPIC_ERROR_UNKNOWN_TOPIC	Reserved for future use.

enum TopicsServiceErrorCode {
  TOPIC_ERROR_INTERNAL,
  TOPIC_ERROR_NO_SERVICE,
  TOPIC_ERROR_TOPIC_NAME_REQUIRED,
  TOPIC_ERROR_ATTACHMENT_NAME_REQUIRED,
  TOPIC_ERROR_PROJECT_NAME_REQUIRED,
  TOPIC_ERROR_TOPIC_CLOSED,
  TOPIC_ERROR_ACTION_CLOSED,
  TOPIC_ERROR_TOPIC_DELETED,
  TOPIC_ERROR_ACTION_DELETED,
  TOPIC_ERROR_UNAVAILABLE_TOPIC,
  TOPIC_ERROR_UNKNOWN_TOPIC
}

Upload files for .NET

.NET clients must first stream files to the server and include a GUID in the attachmentInput parameter, and then call one of the attach methods attachTopic, attachNewTopic, or attachAction. Java clients do not use this method as the Java dataHandler field in AttachmentInput class handles the streaming of the file.

void streamFileAttachment(TopicsServiceContext topicsServiceContext, String guid, 
                          byte[] dataHandler, int bufferSize, int offSet)
throws InvalidArgumentException, TopicsServiceException;

When importing the WSDL with.NET, the dataHandler parameter is a byte array.