Module: common

Enumeration: ErrorCode

The ErrorCode enum is returned in the SystemException object thrown or returned by handlers. This is included here to explain what response codes we return and what they mean.

BAD_REQUEST	400	This error is returned if the *request* is invalid eg, formatted badly, or type errors.
UNAUTHORIZED	401	This means that no authentication token was passed to a service endpoint which requires authentication. This is also used for invalid username/password submissions
FORBIDDEN	403	When a user is authenticated and authorized but the resource is unavailable, such as a disabled team.
NOT_FOUND	404	This error is intended to mean that the entity you are requesting or attempting to manipulate does not exist or is not visible due to authorization control. However, it is currently sometimes returned when the system makes an internal query which unexpectedly returns no results. We are tidying this up.
PRECONDITION_FAILED	412	This error code usually means that the object you are trying to manipulate is not in the correct state for the intended action. We are going to try and phase this out of our application so its only caused by db errors so its easier to react to.
WRONG_STATE	413	Very similar to the above error, but this one only is caused by our application. There was ambiguity surrounding PRECONDITION_FAILED becasue it was sometimes caused by a db error and sometimes by our application and clients had a hard time knowning how to deal with it.
NOOP	414	This error means that client is trying to do something that's already the case. eg. completing a completed job, etc. Clients are recommended to not surface this error code as an error.
INVALID_VERSION	420	The version of an item specified does not exist
UNSUPPORTED_VERSION	421	The action cannot be performed on the version specified, typically due to it being before a sunrise date for recording data necessary for the action to be performed.
JOB_NOT_ACTIVE	422	Job is not active
USER_NOT_ASSIGNED_TO_JOB	423	user is not assigned to particular job
INSUFFICIENT_ROLE_PERMISSIONS	424	user doesn't have sufficient permission
RATE_LIMIT_EXCEEDED	429	Request Limit exceeded - Too Many Requests
INVALID_REGION	430	This means you sent the request to the wrong API server. See the documentation on authentication.LoginResult for how to determine the correct API server for requests.
INVALID_STEP_STATE_TRANSITION	435	The step state transition is not valid for the current user.
REVERT_DISALLOWED	440	A revert action has been refused, typically due to concurrent activity on the item.
MISSING_METADATA	472	An action was attempted on an object that required metadata to be set which was not set.
USER_ALREADY_PART_OF_TEAM	473	An 'addUserToTeam' call was made for a user already on it.
ACCOUNT_UNVALIDATED	474	For security, newly created accounts must click the link in the issued email before they can log in.
TEAM_ALREADY_EXISTS	475	a 'createTeam' call was made, but the domain specified is already in use or reserved
INSUFFICIENT_PERMISSIONS	476	The user does not have the necessary permissions to carry out the requested action. This can be because they are not a member of the team or job, or because they are lacking the correct role. It can also be becasue they are not admins.
USER_NOT_ON_TEAM	477	An 'removeUserFromTeamWithValidation' or 'modifyUserOnTeamWithValidation' call was made for a user not on the team.
ATTRIBUTE_UPDATE_REJECTED	480	The action would result with an object in an ORPHAN or BLIND state
INVALID_TOKEN	497	an authentication token was passed, but it did not validate successfully
TOKEN_EXPIRED	498	a valid authentication token was passed, but it was too old
UNKNOWN_ERROR	499	catch-all for errors missing their own code
INTERNAL_SERVER_ERROR	500	the system could not complete the operation due to a bug
MAX_LIMIT_EXCEEDED	501	A limit on the data has been reached
SERVICE_UNAVAILABLE	503	The server is currently unable to handle the request
NOT_ALLOWED	550	requested operation was rejected for reasons out of callers control
TEMPLATE_NOT_LOCKED	600	can't make changes or release without first acquiring a lock
RESOURCE_ARCHIVED	601	cannot perform action due to archived resource *
WORKFLOW_NOT_LOCKED	602	cannot perform action when the workflow is not locked
WORKFLOW_LOCKED	603	cannot perform action when the workflow is locked (for example, by a different user)
WORKFLOW_QUOTA_EXCEEDED	604	indicates that the max number of unarchived workflows has been reached
WORKFLOW_INSTANCES_DAILY_QUOTA_EXCEEDED	605	indicates that the max number of daily allowed workflow instances has been reached
WORKFLOW_MAX_SIZE_EXCEEDED	606	indicates that the max size for a workflow has been reached

Typedef: UUID

Base type: string

Most ID values in the API are UUIDs. These can be treated as opaque strings, or interpreted according to RFC4122.

Typedef: TimeInSecs

Base type: i64

Timestamps are represented in the API as 64-bit unix timestamps (i.e., seconds since midnight, January 1st, 1970 in UTC).

Struct: UUIDSet

Key	Field	Type	Description	Requiredness	Default value
1	ids	set<UUID>		default

Collection of UUIDs

Struct: VersionRef

Key	Field	Type	Description	Requiredness	Default value
1	id	UUID	the template ID	required
2	publicVersion	i32	The published version of the template being specified	optional
3	internalVersion	i32	The (internal) version being specified	optional

This structure is used to refer to a particular version of a template or template set.

Exception: SystemException

Key	Field	Type	Description	Requiredness	Default value
1	errorCode	ErrorCode	the nature of the error	default
2	message	string	an English string describing the error condition	default
3	localizedMessage	string	if the request set the Accept-Language header to include a supported language, then this field will (in the future) have a localized error string in that language.	default
4	slug	string	a unique key corresponding to the error condition for client-side localization	default
5	rqId	string	the server request ID, where available. Useful for enquiring about confusing responses with support	default
6	errorKey	string	optional string that differentiates different client dialog popups for the same type of error	optional

The SystemException type is returned as the 'throws' type for most service endpoints, as well as certain endpoints which can explicitly return it.

Struct: PageReq

Key	Field	Type	Description	Requiredness	Default value
1	pageToken	string	an opaque token from a PageInfo structure which allows resuming of a streamed set.	optional
2	size	i32	Number of items per page. Requests for pages larger than the default are not guaranteed to be honored.	default	25
3	skip	i32	Number of pages to skip at the beginning of the stream.	optional
4	count	bool	opt in for streaming behavior (see explanation)	optional
5	preview	i32	Return this number of extra page tokens for pages beyond the end of the set	optional

This data structure is used to request pagination or streaming of data from endpoints that support it. This allows result sets larger than can be returned within the request timeout to be retrieved piecemeal.

The first time you call a streaming endpoint and pass this structure, you'll get back a PageInfo object which includes a pageTokens for one subsequent page.

To retrieve the next page, pass the token for that page as the pageToken field in this struct. Use of these tokens to resume allows the system to efficiently stream through the data set. With an appropriate sort order, repeating this until no more token is returned allows you to retrieve all data with "at least once" retrieval semantics for each item in the set.

If the results are being navigated by a user interface, and the user selects to move forward a number of pages, set the skip parameter. The endpoint will return the requested page of data, a pageToken for the page after that, and usually also pageToken values for the skipped pages.

If the interface shows a handful of page numbers allowing the user to skip forward to a handful of nearby pages, it's possible to request the page tokens for these pages in advance using the preview parameter. This gives you a "preview" of the page tokens for those pages, to facilitate paging forward this small number of pages without using skip.

If the interface shows a final page number to indicate the number of results which matched the user query, it has two options to do this. The first is to issue a combined query which both counts results and returns a page of data. This is the default, backwards-compatible behavior, when count is not specified. The count is accurate as of the time it was issued; however, it is possible that by the time the end of the set is reached that there are more (or even fewer) pages of data. The last page of results will always have left equal to zero and no pageToken for any pages beyond the page number (the num field).

The second, and faster approach, is to first issue a query with count set to false, and (optionally) a small number such as 1 or 2 passed as preview. This query mode avoids counting items just to know how many pages there are, which means the left field will not be an accurate predictor of the number of pages left in the results. When rendering the results, if the value of left returned is the same as or lower than the sent value of preview, then the total number of pages in the results can be assumed to be the highest page number in the page tokens that are returned, and the page numbers can be shown to the user as the complete list of pages. The count is avoided. If left is higher than that, then there is at least one more page of results. If the user is interested in the total number of pages (such as by exposing the screen area where the count is shown, or by clicking on a control to request it), then a second call can be issued with the count parameter set to true. This second request will return just the count of pages (i.e. the left field will be accurate). This, in combination with the skip option, can let the user access the last page of results. However, when designing such an interface, a preference should be made towards encouraging the user to reverse the sort order or refining their search terms, rather than performing large seeks through the set or attempting to access the last page.

Users wishing to retrieve every item, such as batch ETL jobs, can set count to false or leave it not set; the only side effect of not setting it is that the first page of results will take slightly longer to retrieve while the system counts the items.

Struct: PageInfo

Key	Field	Type	Description	Requiredness	Default value
1	num	i32	The current page's number. The first page is page 1.	default
2	left	i32	The number of pages left. If the count parameter was set to false to the query, then this can be less than the number of pages remaining, but it will always be non-zero if there are more pages of data.	default
3	pageTokens	map<i32, string>	Page tokens for nearby pages. The keys of this map are the page numbers, and the value is an opaque printable character string which can be passed as the pageToken field in PageReq to request that page.	default

This data structure is included in the result for endpoints which support pagination or streaming of results.

To facilitate efficient paging around the results with the fewest possible API calls, it is appropriate to cache the pageToken values by merging into a client-side map, but the items in the map should be invalidated in the following situations:

• when paging backwards, if any token mismatches the previously held token for that page number, all following cached tokens should be discarded.
• When changing the query terms or sort order, all tokens should be discarded.

This behavior can be approximated by always discarding any old tokens with a higher page number than the highest page number in the pageTokens map, and then merging in.

Struct: AddAction

Key	Field	Type	Description	Requiredness	Default value
1	id	string		default
2	position	i32		default
3	extraInfo	map<string, string>	extraInfo is an api-specific map that is used to attach extra info about added item One use case is in MultiActionTemplates For AddAction to attach the selected data sheet set id -> data sheet id for templates with data sheet definition references, which is a requirement for reference resolution	optional

Struct: RemoveAction

Key	Field	Type	Description	Requiredness	Default value
1	id	string		default
2	position	i32		default

Struct: MoveAction

Key	Field	Type	Description	Requiredness	Default value
1	id	string		default
2	oldPosition	i32		default
3	newPosition	i32		default

Struct: EditAction

Key	Field	Type	Description	Requiredness	Default value
1	id	string		default
2	position	i32		default
3	extraInfo	map<string, string>	extraInfo is an api-specific map that is used to attach extra info about added item One use case is in MultiActionTemplates For EditAction to attach the selected data sheet set id -> data sheet id for templates with data sheet definition references, which is a requirement for reference resolution	optional

Union: ListActions

Key	Field	Type	Description	Requiredness	Default value
1	add	AddAction		default
2	remove	RemoveAction		default
3	move	MoveAction		default
4	edit	EditAction		default

Struct: ExternalOpts

Key	Field	Type	Description	Requiredness	Default value
1	externallyManaged	bool	true if content is continually being externally managed, false if one-time import	optional
2	externalSystemName	string	external system name	optional
3	externalId	string	external id, should be unique	optional
4	externalVersion	string	external version for the external id + system	optional

Options for externally managed content, used by import-related services.

Struct: SelectedListValues

Key	Field	Type	Description	Requiredness	Default value
1	values	set<string>	Multi-select list uses an unordered set of selected string values	default

Struct: SelectedListValueIds

Key	Field	Type	Description	Requiredness	Default value
1	valueIds	set<string>	Multi-select list uses an unordered set of selected string value ids	default

Struct: PreciseNumber

Key	Field	Type	Description	Requiredness	Default value
1	number	double		default
2	precision	byte	Definition of precision on a number: All non-zero digits are significant. Zeros between non-zero digits are significant. Leading zeros are never significant. In a number with a decimal point, trailing zeros (those to the right of the last non-zero digit) are significant. This is counted when user inputs the number as a string.	default

Number input with precision