Task Status Codes

When a task is invoked through the Task Infrastructure, there are a number of possible outcomes. Regardless of the type of content generated, the caller has access to both a “task status code” and an “error message” to interpret the response. The numeric values of the task status codes are modeled after the HTTP status codes, though not strictly.

There are three classes of status codes:

• Success codes. The request was well-formed, the task was properly configured, and the desired content was generated. This is the only class of status codes for which embedded content (generated by the task) is returned.  

• Client/Caller Errors. The caller did not correctly specify something that was needed to get the desired content. This type of condition is considered “non-fatal”. Some amount of input parameter tweaking is necessary to obtain the content.  

• Task Errors. The incoming request is fine, but something is wrong with the task or its environment. Some specific status code indicate a fatal condition, which renders the task completely unusable.  

The sections below describe each class of status codes and the individual values contained in them. All individual status codes are defined in com.microstrategy.web.tasks.TaskStatusCodes.

Success codes

There is only a single status code in this class.

• statusCode=200. TASK_SUCCESS. No exceptions were raised. It is safe to inspect the embedded content.

  • errorMsg=“Success”

Client/Caller Errors

All of these status codes are non-fatal. In addition to the status code and error message, there are instructions to the caller on how to take corrective action and how a task designer can indicate this condition.

• statusCode=303. TASK_NOT_REQUESTED. The taskID parameter (that is, the parameter whose value uniquely identifies the task) was not specified.

  • errorMsg contains a message that includes the proper spelling of the taskID parameter. 

  • Corrective Action: Use the correct parameter name. 

  • How to Invoke from Task: A task designer does not raise this exception. It is raised by the Task Infrastructure.

• statusCode=404. TASK_NOT_FOUND. ThetaskIDparameter (that is, the parameter whose value uniquely identifies the task) was specified, but it does not refer to a task that is registered.

  • errorMsg contains a message that lists the Task IDs of all registered tasks. 

  • Corrective Action: Use a registered Task ID as the value of the taskID parameter. 

  • How to Invoke from Task: A task designer does not raise this exception. It is raised by the Task Infrastructure. 

• statusCode=400. TASK_REQUEST_MALFORMED. A proper taskID parameter (that is, the parameter whose value uniquely identifies the task) was specified, but required parameters were missing or some other form of task-specific validation failed.

  • errorMsg indicates what caused the failure. 

  • Corrective Action: Display a message to the user to correct the incorrect task invocation. 

  • How to Invoke from Task: The Task Infrastructure raises this on the task designer’s behalf by inspecting required parameters. If any additional validation (performed by the task itself) fails, this condition can be raised by calling: 

  Copy

  throw new TaskRequestMalformedException(errorMsg);

  where errorMsg is the string to return to the caller.

Task Errors

These errors are semi-fatal and totally fatal.

• statusCode=500. TASK_INTERNAL_ERROR. There is no problem with the request or the task configuration, but something unexpected happened. A task-specific error code can be inspected by the caller to see if the task can be made to work with a different set of input parameters.

  • errorMsg indicates the reason for the failure. 

  • taskErrorCode is a task-specific error code that can be used by the caller to figure out what action to take. 

  • Corrective Action: Inspect the task error code, make changes if possible, and try again. 

  • How to Invoke from Task: To convey this condition from inside a task, use one of the following:

    Copy

    throw new TaskInternalException(taskErrorCode, errorMsg);

    Copy

    throw new TaskInternalException(mstrCheckedException);

    where taskErrorCode is a numeric error code and mstrCheckedException is an instance of a MSTRCheckedException. In this case, the error code and message are extracted using the getErrorCode and getMessage methods.

• statusCode=503. TASK_MISCONFIGURED. There is no amount of input tweaking to make this task work. Typical reasons include a bean-based task that specifies a hard-coded style which does not exist in the Style Catalog Configuration file, the web bean necessary to handle the task could not be created, the task did not initialize properly, bad class name, etc.

  • errorMsg indicates the reason for failure. 

  • Corrective Action: None. Don’t call this task again. 

  • How to Invoke from Task: The Task Infrastructure typically raises this type of exception. If a task wishes to raise this condition, it must do so sparingly. To raise, use:

    Copy

    throw new TaskConfigurationException(errorMsg);