MKS Integrity 2007 Integrations Builder Guide

Chapter 3: Using the MKS API
20
There are also API-specific default preferences that are used in special situations. For
example, the default set of fields shown in a view command in the API are specially defined
as API defaults and are not subject to changes that may be reflected in the GUI.
Executing a Command
The command runner executes the command and passes it to the integration point. The
integration point runs the command and returns a response, which contains all information
related to the execution of the command. The response contents can then be accessed or
another command can be run. Each command execution generates a new response. For more
information on accessing response contents, see “Reading Responses” on page 20.
If a command specified for the Java API ends in an error, a command level exception is
thrown and should be caught. For more information, see “Catching Exceptions” on page 29.
Reading Responses
A response contains all of the output from executing a command. All commands communicate
using the same response type, but use the response differently depending on the type of
command and what it needs to communicate. This section describes the response for the
creation, action, and view command types.
NOTE Often it is useful to know the host, port, and user that a command used to
connect to the MKS Integrity Server. The MKS API has functions and methods to
return this information. For more information, see the MKS Java API documentation
or the MKS ANSI C API documentation.
To find any errors that occurred as part of the response for a command specified for the C
API, you need to search for them explicitly. For more information, see “C API Application
Errors” on page 33.
Creation Commands
Creation commands create something new, for example, an MKS Integrity item. The command
names usually start with the word “create”. The response for a creation command
communicates the item that was created or what errors prevented the item from being
created.
If the command ran successfully, the result contains information about what was created. The
result message is the same text shown by the CLI, for example, “Created issue 123”.
If you want to continue working with the created item, you do not need this message; you
only need the ID of what was created. The following examples show how to retrieve the item
ID from the result.