Messages  Programming Messages

On this page, you will find information about common messages, including usage information. Click here to show all details. Also, see recipes and entities. Below is a list of property markers:

entity Entity Indicates that the property contains a wrapped entity. Depending on the type of message, only some properties of the entity may need to be set.
object Object Indicates that the property contains a wrapped object which is not an entity. For example, this could be a condition restriction object.
array Array Indicates that the property is in fact an array containing multiple simple values, multiple wrapped entities, etc.
Message

CreateMessage

Allows callers to create an entity.
Click here to view properties.

  • Instance (Entity entity):
       Entity to create
  • Ticket (String):
       Authentication ticket
  • Version number (String):
       Version

Click here to view usage notes.

  • Properties which are calculated (ex: CreatedBy) will be ignored
  • if the request does not specify an ID for the entity, one is automatically generated and specified in the response.
  • In many cases, some properties are mandatory on create (ex: WorkspaceInfoId for entities stored under Workspaces).
  • For more information about optimizing requests, click here.
  • For more information about setting properties, click here.
  • For more information about message versioning, click here.
Message

UpdateMessage

Allows callers to update an entity.
Click here to view properties.

  • Instance (Entity entity):
       Entity to update
  • UpdateFieldsXml (String):
       XML specifying which properties to update (if null, all properties should be updated)
  • Ticket (String):
       Authentication ticket
  • Version number (String):
       Version

Click here to view usage notes.

  • Properties which are calculated (ex: CreatedBy) or set once will be ignored.
  • The ID property is always mandatory for all update requests, so that the entity can be located.
  • In some cases, additional properties must be specified, so that the entity can be located (ex: WorkspaceInfo.Id for tasks).
  • As a way to optimize requests, properties whose value is the default can be omitted from XML.
  • Although such properties may not appear in submitted update XML, they will be considered specified.
  • Accordingly, by design, update requests may reset (apparently) unspecified properties to their default values.
  • Therefore, we recommend explicitly specifying which properties should be updated (using UpdateFieldsXml).
  • If you omit UpdateFieldsXml, ensure all updateable properties are set to their expected values.
  • For more information about optimizing requests, click here.
  • For more information about setting properties, click here.
  • For more information about message versioning, click here.
Message

DeleteMessage

Allows callers to delete an entity.
Click here to view properties.

  • Instance (Entity entity):
       Entity to delete
  • Ticket (String):
       Authentication ticket
  • Version number (String):
       Version

Click here to view usage notes.

  • The ID property is always mandatory for all delete requests, so that the entity can be located.
  • In some cases, additional properties must be specified, so that the entity can be located (ex: WorkspaceInfoId for tasks).
  • For more information about optimizing requests, click here.
  • For more information about setting properties, click here.
  • For more information about message versioning, click here.
Message

RetrieveMessage

Allows callers to find and retrieve non-task entities.
Click here to view properties.

  • TypeName (String):
       Name of the type of entity to retrieve
  • StartIndex (Integer):
       Index at which entities should be retrieved (used for paged retrieves)
  • Count (Integer):
       Number of entities which should be retrieved (used for paged retrieves)
  • ConditionRestriction (SelectConditionRestriction object):
       Optional condition restriction specifying which results to retrieve, how to order results, and how to group results
  • Instances (Entity[] entityarray):
       Retrieved instances
  • RetrieveFieldsXml (String):
       XML specifying which properties to retrieve (if null, all properties should be retrieved)
  • IncludePendingApproval (Boolean):
       If true, entities in workspaces to which the caller was granted rights but which are still pending, are also retrieved
  • Ticket (String):
       Authentication ticket
  • Version number (String):
       Version

Click here to view usage notes.

  • This message cannot be used to retrieve task or task result entities.
  • If the Count property is set to 0, as many entities as possible will be retrieved.
  • However, the maximum number of entities which can be retrieved by one request is 1000.
  • Also note that if the response XML is too large, an error may be received because of an exceeded max packet size.
  • Therefore, we recommend implementing paging and requesting a reasonable count.
  • Therefore, we recommend explicitly specifying which properties you are interested in retrieving.
  • For more information about retrieving data, click here.
  • For more information about paging retrieves, click here.
  • For more information about message versioning, click here.
Message

RetrieveTaskMessage

Allows callers to find and retrieve task entities.
Click here to view properties.

  • WorkspaceInfo (WorkspaceInfo entity):
       Workspace from which to retrieve tasks
  • TypeName (String):
       Name of the type of task to retrieve
  • StartIndex (Integer):
       Index at which entities should be retrieved (used for paged retrieves)
  • Count (Integer):
       Number of entities which should be retrieved (used for paged retrieves)
  • ConditionRestriction (SelectConditionRestriction object):
       Optional condition restriction specifying which results to retrieve, how to order results, and how to group results
  • Instances (Entity[] entityarray):
       Retrieved instances
  • RetrieveFieldsXml (String):
       XML specifying which properties to retrieve (if null, all properties should be retrieved)
  • IncludePendingApproval (Boolean):
       If true, entities in workspaces to which the caller was granted rights but which are still pending, are also retrieved
  • Ticket (String):
       Authentication ticket
  • Version number (String):
       Version

Click here to view usage notes.

  • This message is used to retrieve tasks.
  • If the Count property is set to 0, as many tasks as possible will be retrieved.
  • However, the maximum number of tasks which can be retrieved by one request is 1000.
  • Also note that if the response XML is too large, an error may be received because of an exceeded max packet size.
  • Therefore, we recommend implementing paging and requesting a reasonable count.
  • Therefore, we recommend explicitly specifying which properties you are interested in retrieving.
  • The WorkspaceInfo property should specify the Id property, so that tasks can be located.
  • For more information about retrieving data, click here.
  • For more information about paging retrieves, click here.
  • For more information about message versioning, click here.
Message

RetrieveTaskResultMessage

Allows callers to find and retrieve task result entities.
Click here to view properties.

  • RootAlgorithmTaskInfo (RootAlgorithmTaskInfo entity):
       Task whose results should be retrieved
  • TypeName (String):
       Name of the type of task result to retrieve
  • StartIndex (Integer):
       Index at which entities should be retrieved (used for paged retrieves)
  • Count (Integer):
       Number of entities which should be retrieved (used for paged retrieves)
  • ConditionRestriction (SelectConditionRestriction object):
       Optional condition restriction specifying which results to retrieve, how to order results, and how to group results
  • Instances (Entity[] entityarray):
       Retrieved instances
  • RetrieveFieldsXml (String):
       XML specifying which properties to retrieve (if null, all properties should be retrieved)
  • IncludePendingApproval (Boolean):
       If true, entities in workspaces to which the caller was granted rights but which are still pending, are also retrieved
  • Ticket (String):
       Authentication ticket
  • Version number (String):
       Version

Click here to view usage notes.

  • This message is used to retrieve task results.
  • If the Count property is set to 0, as many tasks as possible will be retrieved.
  • However, the maximum number of tasks which can be retrieved by one request is 1000.
  • Also note that if the response XML is too large, an error may be received because of an exceeded max packet size.
  • Therefore, we recommend implementing paging and requesting a reasonable count.
  • Therefore, we recommend explicitly specifying which properties you are interested in retrieving.
  • The RootAlgorithmTaskInfo property should specify the ID of the task to retrieve results for.
  • The RootAlgorithmTaskInfo property should specify the WorkspaceInfoId property, so that task results can be located.
  • For more information about retrieving data, click here.
  • For more information about paging retrieves, click here.
  • For more information about message versioning, click here.
Message

RetrieveDataMessage

Allows callers to find and retrieve data rows.
Click here to view properties.

  • Download (Boolean):
       Whether, instead of sending a RetrieveDataMessage response, the Web service should stream out raw data in CSV format
  • LineSeparator (String):
       Separator to use to format streamed CSV data (applies only when Download is true, defaults to "," if unspecified)
  • CultureName (String):
       Culture to use to format streamed CSV data (applies only when Download is true, defaults to the neutral culture if unspecified)
  • JoinRestriction (JoinRestriction object):
       Optional join restriction specifying how to join data rows with specific task results
  • TableInfo (TableInfo entity):
       Data table from which data rows should be retrieved
  • StartIndex (Integer):
       Index at which data rows should be retrieved (used for paged retrieves)
  • Count (Integer):
       Number of data rows which should be retrieved (used for paged retrieves)
  • ConditionRestriction (SelectConditionRestriction object):
       Optional condition restriction specifying which results to retrieve, how to order results, and how to group results
  • DataXml (String):
       Retrieved data rows in XML format
  • RetrieveFieldsXml (String):
       XML specifying which data fields to retrieve (if null, all data fields should be retrieved)
  • IncludePendingApproval (Boolean):
       If true, entities in workspaces to which the caller was granted rights but which are still pending, are also retrieved
  • RowCount (Integer):
       Count of rows actually retrieved (could be less than the specified retrieve count)
  • Ticket (String):
       Authentication ticket
  • Version number (String):
       Version

Click here to view usage notes.

  • When the Download property is set to true, no response XML is sent: instead, a CSV file is streamed out.
  • You can specify how streamed CSV content should be formatted using properties LineSeparator and CultureName.
  • For example, US CSV files may specify dates in MM/DD/YY format.
  • However CSV files generated in other locales may differ.
  • If the Count property is set to 0, as many rows as possible will be retrieved.
  • If Download is true, content will continue to be streamed out until completion.
  • If Download is false, the maximum number of rows which can be retrieved by one request is 1000.
  • Also note that if the response XML is too large, an error may be received because of an exceeded max packet size.
  • Therefore, we recommend implementing paging and requesting a reasonable count.
  • Therefore, we recommend explicitly specifying which properties you are interested in retrieving.
  • The DataXml format is <row><cell>value1</cell><cell>value2</cell>…</row>.
  • If the RetrieveFieldsXml property is specified, <cell> tags match the order in which fields were specified.
  • If the RetrieveFieldsXml property is not specified, <cell> tag values match the original field order in uploaded data.
  • The RowCount property allows callers to know how many data rows were retrieved without having to parse returned DataXml.
  • For more information about retrieving data, click here.
  • For more information about paging retrieves, click here.
  • For more information about message versioning, click here.
Message

StartTaskMessage

Allows callers to start a task.
Click here to view properties.

  • RootAlgorithmTaskInfo (RootAlgorithmTaskInfo entity):
       Task to start
  • Ticket (String):
       Authentication ticket
  • Version number (String):
       Version

Click here to view usage notes.

  • Tasks which have already been started cannot be started again.
  • The RootAlgorithmTaskInfo property should specify the ID of the task to start.
  • The RootAlgorithmTaskInfo property should specify the WorkspaceInfoId property, so that the task can be located.
  • For more information about executing tasks, click here.
  • For more information about message versioning, click here.
Message

ErrorMessage

Allows the Web service to report errors.
Click here to view properties.

  • ErrorCode (Enum):
       Error code
  • ErrorDetails (String):
       Error details
  • Ticket (String):
       Authentication ticket
  • Version number (String):
       Version

Click here to view usage notes.

  • Normally, a response of the same type as the request is received.
  • However, when an error occurs, an ErrorMessage response is received instead.
  • For more information about handling errors, click here.
  • For more information about message versioning, click here.
Message

LogonMessage

Allows callers to log in and obtain an authentication ticket as well as account information.
Click here to view properties.

  • Instance (UserInfo entity):
       Account information to authenticate with (user name & password) / returned complete account information
  • Ticket (String):
       Returned authentication ticket

Click here to view usage notes.

  • Ensure the user name and password are specified when submitting the log in request.
  • The user account must have been registered and fully activated before login requests can succeed.
  • The obtained authentication ticket should be used to authenticate subsequent requests.
  • For more information about authenticating requests, click here.
  • For more information about message versioning, click here.
Message

CaptchaMessage

Allows callers to obtain a CAPTCHA challenge which must be solved to register a new account.
Click here to view properties.

  • UserName (String):
       Name of the account to register
  • CaptchaImage (String):
       Returned base-64 encoded CAPTCHA image (in jpeg format)
  • CaptchaHash (String):
       Keyed hash of the CAPTCHA text within the CAPTCHA image
  • Ticket (String):
       Not used

Click here to view usage notes.

  • Visually render the CAPTCHA image, and obtain a response to the CAPTCHA challenge from the user.
  • Make sure the same user login name is used by the CaptchaMessage and RegisterMessage calls.
  • Make sure the same same CaptchaHash property is used by the CaptchaMessage and RegisterMessage call.
  • For more information about registering users, click here.
  • For more information about message versioning, click here.
Message

RegisterMessage

Allows callers to register a new user account after solving a CAPTCHA challenge.
Click here to view properties.

  • CaptchaHash (String):
       CAPTCHA hash returned by a CaptchaMessage response
  • CaptchaString (String):
       Proposed solution to the CAPTCHA challenge
  • Instance (UserInfo entity):
       Information about the user to register
  • Ticket (String):
       Returned authentication ticket

Click here to view usage notes.

  • Before submitting a RegisterMessage request, submit a CaptchaMessage request to obtain a CAPTCHA challenge.
  • Upon execution, the server will hash the submitted solution, and compare it with the supplied hash to verify it is correct.
  • Make sure the same user login name is used by the CaptchaMessage and RegisterMessage calls.
  • Make sure the same same CaptchaHash property is used by the CaptchaMessage and RegisterMessage call.
  • If an e-mail registration confirmation is required to acivate the account, no ticket will be returned by the response.
  • For more information about registering users, click here.
  • For more information about message versioning, click here.
Message

SendPasswordResetMessage

Allows callers to request that a passord reset e-mail be sent.
Click here to view properties.

  • Name (String):
       Name of the account for which a password reset e-mail should be sent
  • Ticket (String):
       Not used

Click here to view usage notes.

  • Ensure the feature which enables password reset e-mails has been enabled.
  • If too many e-mails have been requested for a user, the request will be rejected.
  • For more information about configuration options, click here.
  • For more information about message versioning, click here.
Message

SendRegistrationConfirmationMessage

Allows callers to request that a registration confirmation e-mail be re-sent.
Click here to view properties.

  • Name (String):
       Name of the account for which a registration confirmation e-mail should be re-sent
  • Ticket (String):
       Not used

Click here to view usage notes.

  • Ensure the feature which enables account confirmation e-mails has been enabled.
  • If too many e-mails have been requested for a user, the request will be rejected.
  • If the account has already been confirmed and activated, the request will be rejected.
  • For more information about configuration options, click here.
  • For more information about message versioning, click here.
Message

WhoAmIMessage

Allows callers to present an authentication ticket and obtain corresponding user account information.
Click here to view properties.

  • Instance (UserInfo entity):
       Returned information about the user account associated with the presented authentication ticket
  • Ticket (String):
       Authentication ticket to resolve to a user account

Click here to view usage notes.

  • This message allows you to translate a (for example, persisted) ticket to a user identity, enabling easy sign in or user impersonation scenarios.
  • For more information about authenticating requests, click here.
  • For more information about message versioning, click here.
Message

RestrictAccessMessage

Allows callers to present an authentication ticket and obtain a more restricted ticket.
Click here to view properties.

  • SecurityRestriction (SecurityRestriction entity):
       Security restriction specifying a set of usage restrictions
  • Ticket (String):
       Authentication ticket to restrict
  • RestrictedTicket (String):
       Response restricted authentication ticket

Click here to view usage notes.

  • This message allows you to obtain a more restricted version of a ticket.
  • For example, you could use a RightLevelRestriction to lower any right the ticket has on any workspace to no more than "read".
  • For example, you could use a InvocationRestriction to only allow Read operations on TableInfo entities.
  • For example, you could use a WorkspaceInfoRestriction to restrict access to a specific workspace.
  • For example, you could use a ExpirationRestriction to issue short-lived tickets valid for 5 minutes.
  • For more information about authenticating requests, click here.
  • For more information about message versioning, click here.
Message

RetrievePerfMessage

Allows callers to retrieve general performance information about tasks.
Click here to view properties.

  • Tasks (Integer[] array):
       Returned information about the total number of tasks executing or remaining to execute (pending, scheduled, or started).
  • RunningTasks (Integer[] array):
       Returned information about the number of tasks currently executing.
  • Ticket (String):
       Authentication ticket
  • Version number (String):
       Version

Click here to view usage notes.

  • This message allows you to obtain general performance information about system load and task execution progress.
  • All returned values are not specific to the caller, but rather to the entire system.
  • Both tasks started by users, and child sub-task they may have spawned, are counted.
  • The last value in each array property contains the most recently observed task count.
  • Other values in each array property contain previously observed task counts (the time interval is unspecified).
  • Counts for the Tasks property exclude tasks which failed and cannot be retried, but includes tasks which failed but will be retried.
  • For more information about authenticating requests, click here.
  • For more information about message versioning, click here.
Message

ComplexMessage

Allows callers to batch requests.
Click here to view properties.

  • Messages (Message[] entityarray):
       Sequence of messages to execute
  • StopOnError (Boolean):
       Whether execution of the sequence should stop if an error is encountered
  • Ticket (String):
       Authentication ticket
  • Version number (String):
       Version

Click here to view usage notes.

  • Using complex messages to batch requests is entirely optional (simple messages can be submitted standalone).
  • The specified sequence of messages is executed in order, but without any type of transactional behavior.
  • The complex response contains one response message for each request message in the specified sequence.
  • Messages in the specified sequence should only be simple messages (i.e. not complex messages).
  • If no authentication ticket is specified by the complex message, each message in the sequence must specify one.
  • If an authentication ticket is specified by the complex message, each message in the sequence need not specify one.
  • If an authentication ticket is specified by both the complex message and a message in the sequence, the latter one is used.
  • For more information about batching requests, click here.
  • For more information about message versioning, click here.
Message

ParseExpressionMessage

Allows callers to verify that an expression is valid and parse it as an expression tree.
Click here to view properties.

  • Expression (String):
       Text expression to parse
  • LogicalExpression (LogicalExpressionentity):
       A logical expression representing the root of the expression tree
  • Ticket (String):
       Authentication ticket
  • Version number (String):
       Version

Click here to view usage notes.

  • Expressions are used by SetTransform data transformation steps.
  • For more information about transforming data, click here.
  • For more information about message versioning, click here.

The following objects and enums are used to support messages:

Object

SecurityRestriction

Represents a list of restrictions to apply when requesting a restricted ticket.
Click here to view properties.

  • AccessRestrictions (AccessRestriction[] entityarray):
       Array of restrictions to impose

Click here to view usage notes.

  • For example, you could specify both a workspace and an expiration restriction
  • For more information about restricting access, click here.
Object

RightLevelRestriction

A restriction which lowers the right level the original ticket has on different workspaces.
Click here to view properties.

  • RightLevel (RightLevel):
       The maximum allowed right level

Click here to view usage notes.

  • For example, you could use a RightLevelRestriction to lower any right the ticket has on any workspace to no more than "read".
  • For more information about restricting access, click here.
Object

InvocationRestriction

A restriction which specifies which restricts which web service calls are allowed.
Click here to view properties.

  • TypeName (String):
       The name of an allowed entity (ex: "TableInfo")
  • MessageName (String):
       The name of an allowed message (ex: "DeleteMessage")

Click here to view usage notes.

  • For example, you could use a InvocationRestriction to only allow Read operations on TableInfo entities.
  • For more information about restricting access, click here.
Object

WorkspaceInfoRestriction

A restriction which specifies which restricts the scope to a specific workspace.
Click here to view properties.

  • WorkspaceInfoId (Guid):
       ID of an allowed workspace

Click here to view usage notes.

  • For example, you could use a WorkspaceInfoRestriction to restrict access to a specified workspace.
  • For more information about restricting access, click here.
Object

ExpirationRestriction

A restriction which specifies which restricts the amount of time until which a restricted ticket can be used.
Click here to view properties.

  • Expiration (DateTime):
       Date at which the ticket expires

Click here to view usage notes.

  • For example, you could use a ExpirationRestriction to issue short-lived tickets valid for 5 minutes.
  • For more information about restricting access, click here.
Object

SelectConditionRestriction

A type of Restriction specifying ordering, grouping, and selection clauses.
Click here to view properties.

  • Groupings (Grouping[] entityarray):
       Array of grouping clauses
  • Orderings (Ordering[] entityarray):
       Array of ordering clauses
  • Restrictions (Restriction[] entityarray):
       Array of selection clauses
  • IsOrCondition (Boolean):
       Whether child selection clauses should be combined using an AND or an OR operator

Click here to view usage notes.

  • In most cases, the Restrictions property contain child ValueRestrictions specifying individual selection clauses.
  • However, if multi-level OR/AND clauses are required, the Restrictions property may contain other child SelectConditionRestrictions.
  • If so, ensure child SelectConditionRestrictions do not specify groupings or orderings (they must be specified by the top level SelectConditionRestriction).
Object

Grouping

An object specifying a grouping clause.
Click here to view properties.

  • FieldName (String):
       Name of a data field or of an entity property to group by

Click here to view usage notes.

  • Groupings specify how results should be aggregated.
  • Once grouping is used, aggregate operators can be specified by retrieve requests.
  • The following operators are allowed: COUNT(), SUM(), MAX(), MIN(), AVG(), STDDEV().
  • Simply surround the name of a data field or entity entity property with one of these operators.
Object

Ordering

An object specifying an ordering clause.
Click here to view properties.

  • FieldName (String):
       Name of a data field or of an entity property to order by
  • Descending (Boolean):
       Whether the ordering should be ascending or descending

Click here to view usage notes.

  • Orderings specify in which order results should be returned.
  • To sort by increasing value (or alphabetical order), set Descending to false.
  • To sort by decreasing value (or reverse alphabetical order), set Descending to true.
Object

ValueRestriction

A type of Restriction specifying a selection clause.
Click here to view properties.

  • Value (Object):
       Value to restrict to
  • Condition (Enum):
       Condition operator to use for the restriction
  • FieldName (String):
       Name of a data field or of an entity property to impose a restriction on

Click here to view usage notes.

  • A ValueRestriction imposes a single restriction of a data field or entity property.
  • ValueRestrictions are normally combined using SelectConditionRestrictions.
Object

TaskResultJoinRestriction

A type of JoinRestriction specifying a join between data rows and task results.
Click here to view properties.

  • OwningRootAlgorithmTaskInfo (RootAlgorithmTaskInfo entity):
       Task whose results should be joined with
  • JoinTypeName (String):
       Name of the task result entity to join with
  • Restrictions (Restriction[] entityarray):
       Not used (use the ConditionRestriction property instead)
  • IsOrCondition (Boolean):
       Not used (use the ConditionRestriction property instead)

Click here to view usage notes.

  • Join restrictions are used as a bridge between data rows and task results.
  • For example, you may want to join between data rows and cluster results to get a list of rows which are members of a particular cluster.
  • To specify restriction clauses, use the RetrieveDataMessage's ConditionRestriction property.
  • Once a join has been specified, you can specify restrict / retrieve using both data fields and task entity properties.
  • For more information about using joins, click here.
Object

Condition

Enum specifying a condition operator.
Click here to view properties.

  • StrictLess = 0: specifies that data should be strictly less than the specified value
  • Less = 1: specifies that data should be strictly less than or equal to the specified value
  • Equal = 2: specifies that data should be equal to the specified value
  • Different = 3: specifies that data should be different from the specified value
  • More = 4: specifies that data should be strictly more than the specified value
  • StrictMore = 5: specifies that data should be strictly more than or equal to the specified value
  • In = 6: specifies that data should one of the specified values
  • NotIn = 7: specifies that data should not be one of the specified values
  • Like = 8: specifies that data should match the specified text pattern
  • NotLike = 9: specifies that data should not match the specified text pattern

Click here to view usage notes.

  • Some operators are only applicable to string values (ex: Like).
  • When using the In or NotIn operator, specify an array or values to compare with.
  • When using the Like or NotLike operator, specify a SQL-like comparison string (ex: "x%" means starting with x).