Parameter Glossary

Use the operation usage information for parameters for the Cherwell REST API.

The following conventions are used in this glossary:

  • Internal ID: The database ID for a specific object.
  • Name: Typically, the display name for an object.
  • Public ID: Typically, the ID shown to users, such as an incident ID or a user's full name.
  • Record ID: The database ID for a specific record.
  • Search Item: Saved searches, also known as a stored query.
  • Search Results: A set of records returned by a search.

Business Object attachment operations (requests or responses)

Parameter Operation Usage
allfields A flag to include all related Business Object fields.
attachBusObId The internal ID for the type of Business Object to attach to another Business Object.
attachBusObName The display name for the type of Business Object you want to attach to another Business Object.
attachBusObPublicId The public ID for the type of Business Object you want to attach to another Business Object.
attachBusObRecId The internal ID for the Business Object to attach to another Business Object.
attachedBusObId The internal ID for the type of Business Object attached to another Business Object.
attachedBusObRecId The internal ID for the Business Object attached to another Business Object.
attachmentFileId The internal ID for a file attachment.
attachmentFileName The path and file name of a file attachment.
attachmentFileType The type of file attachment.
attachmentId The internal ID for a record that contains information about a file attachment.
attachments A list of objects related to Business Object attachments.
attachmentTypes The type of file attachment:
  • 0 = Imported into the database.
  • 1 = Linked to an external file.
  • 2 = URL attachment.
body The body of the request is the byte array of the file part being uploaded.
created The date and time an attachment was added to a Business Object.
customSeparator A custom separator for exports to a text file.
filename The name of a file attachment being uploaded.
offset The starting index of the file part being uploaded. For the first part, the offset should be zero.
totalsize The size of a file, in bytes.
uncFilePath A file path to a Business Object linked attachment.

Business Object operations (requests, responses, schema, or template requests)

Parameter Operation Usage
allfields A flag to include all related Business Object fields.
customGridId The internal ID for the grid used to override field list settings.
fieldNames A comma-delimited list of field names. By default, all fields are requested.
firstRecIdField The first Record ID field specified for a Business Object.
foredit For form operations, a flag to get an editable version of a form.
group A flag to indicate that the Business Object is a group leader.
groupSummaries A list of objects for members of a Business Object group.
html The placeholder for the HTML field value. It is only populated on getting field values for rich text fields.
includeAll A flag to include all fields with Business Object templates.
includerelationships A flag to include schemas for related Business Objects. Default is false.
includeRequired A flag to request all required fields with Business Object templates.
lookup A flag indicating a Business Object type of Lookup.
major A flag indicating a Business Object type of Major.
publicid/publicId The public ID used to identify Business Object records.
relatedBusinessObjects A list of objects for related Business Objects.
stateFieldId The internal ID for the State field defined for a Business Object life cycle.
states The display names for State values defined for a Business Object life cycle.
supporting A flag indicating a Business Object type of Supporting.

Field schema responses

Parameter Operation Usage
autoFill A flag that indicates if auto-populate is enabled.
calculated A flag that indicates if an expression is used to calculate the field's value.
caption The title for a column on the Business Object grid.
category A string that indicates the folder used to organize the field.
currencyCulture The Currency Culture set for Number fields.
currencySymbol The currency symbol for the Currency Culture set for Number fields
decimalDigits The number of digits for a Number field that appear in the field value after the decimal point.
details A string of attributes set for a field.
enabled An expression that is being evaluated.
fieldDefinitions A list of properties for each field.
hasDate Indicates if a Date/Time field displays dates.
hasDefaultSortField A flag to indicate if a field has a default sort order. Use with defaultSortOrder.
hasTime Indicates if a Date/Time field displays times.
isBinary A flag to indicate that field contains Binary data, such as an image.
isCurrency A flag to indicate that a Number field stores currency values.
isDateTime A flag to indicate a Date/Time field.
isFilterAllowed A flag to indicate that filtering is allowed.
isFullTextSearchable A flag to indicate if full-text searching is enabled for a field.
isLogical A flag to indicate a Logical field.
isNumber A flag to indicate a Number field.
isShortDate A flag to indicate that a Date/Time field shows dates only.
isVisible A flag to indicate if a field is visible.
maximumSize For text fields, the maximum number of characters allowed.
readOnly A flag to indicate if the field is read only (true) or editable (false).
sortable A flag to indicate that a field is sortable (true) or not sortable (false).
sortOrder Indicates sort order (ascending or descending).
storageName The database name used for a field.
validated A flag to indicate whether validation is defined for the field. See details for validation information.
wholeDigits Indicates the number of whole digits specified for number fields.

Flags

Parameter Operation Usage
dirty A flag to update a field value if true. If false, the value is not updated.
hasError A flag to indicate an error needs to be reviewed.
includelinks A flag to request hyperlinks in results. Default is false.
links For requests, a flag to request hyperlinks in results. Default is false.

For responses, a list of links, including name and URL.

multiline For prompts, a flag to indicate if a text prompt can contain multiple lines.
required A flag to indicate an item is required (true) or optional (false).
saveRequests A list of saveRequest objects that will be processed.
stopOnError A flag to stop or continue on error.
usedefaultgrid A flag to trigger the use of the related Business Objects default grid for the list of fields to return.

Internal IDs or names

Parameter Operation Usage
association The internal ID for the Business Object association.
busobid/busObID The internal ID for a Business Object type, such as Incident or Task.
busobrecid The internal ID for a single Business Object record.
fieldId The internal ID for a field.
folder/folderId The name or internal ID of an item's folder.
formid The internal ID for a form.
gridDefinitions The internal IDs for grids associated with a Business Object.
gridid The internal ID for the custom grid that contains the field list.
name The display name for an object.
owner The internal ID for the Business Object association.
parentbusobid The internal ID for the parent Business Object type.
scope The name or internal ID of an item's scope. For example, Global and Team are scopes.
scopeowner The internal ID or name of the scope owner. For example, if Team is the scope, 1st Level Support might be the scope owner.
userrecordid/userRecID The internal ID for a CSM user.

Mobile form operations (responses)

Parameter Operation Usage
actions A list of action objects available for a form.
altitude The altitude for a specific Business Object record (if location awareness is enabled).
galleryImage The image shown on the form.
id The internal ID for actions available for the form.
label The display name for fields.
latitude The latitude for a specific Business Object record (if location awareness is enabled).
locationInformation A list of location objects for a specific Business Object record.
longitude The longitude for a specific Business Object record (if location awareness is enabled).
multiline A flag to indicate if a field can span multiple lines.
sectionFields A list of fields and attributes for each section on a form.
sections A list of sections available on a form.
targetBusObId The Business Object ID for the Business Object type.
targetBusObRecId The Business Object record ID.
title The display name of a Business Object.

Queue operations (requests or responses)

Parameter Operation Usage
historyNotes Notes to be added to the history log for the item.
historyRecId The record ID of the Business Object with the history.
historyText The text of the history record for the item.
historyTypeId The ID of the Business Object type that holds the history.
queueStandInKey The internal key for a queue derived from its scope, scope owner, and folder.

Quick search operations (operation configuration, requests, or responses)

Parameter Operation Usage
allowQuickSearch A flag to indicate if quick search is allowed.
allowSpecificSearch A flag to indicate if specific search is allowed.
ascending A flag to indicate results are sorted in ascending order.
changedLimits The limits based on changes made in a specific time frame.
columns A list of properties for each field on the Business Object grid. Columns are returned when the schema flag it set to true.
defaultToQuickSearch A flag to indicate that if both quick search and specific search are allowed, quick search is the default (true).
docRespositoryItemID The internal ID for a document repository.
groups A set of objects and a results list for a simple text search.
hasAnyOptions True if search configuration option is set to Display (2) or UseAndDisplay (3).

Option Key

  • 0 = None (Not selected and cannot select.)
  • 1 = Use (Selected and cannot clear.)
  • 2 = Display (Not selected and can select.)
  • 3 = UseAndDisplay (Selected and can clear.)
IncludeAvailableInSpecific A flag to indicate whether available quick search items are included.
IncludeQuickSearchInSpecific A flag to include all items in quick search in specific searches.
isBusObTarget A flag to indicate that the quick search is based on a Business Object (true) or a document repository (false).
key The name of a field used for sorting.
nonFinalStateOption A flag to indicate if closed records are excluded. True excludes closed records. Use the Option Key to determine if you can change this option.
quickSearchId The internal ID of a quick search configuration.
quickSearchItems A set of object for each quick search configuration.
quickSearchWatermark The text provided for the quick search control.
resolvedQuickSearchWatermark The text provided for the quick search control. Custom text is shown if it was provided.
rowColor The row color assigned to a record returned by the search.
rows A list or records returned based on search criteria.
searchAnyWordsOption A flag to indicate whether any or all words will be used in a query. Use the Option Key to determine if you can change this option.
searchAttachmentsOption A flag to indicate whether attachments will be queried. Use the Option Key to determine if you can change this option.
searchRelatedOptions A flag to indicate whether related Business Objects will be queried. Use the Option Key to determine if you can change this option.
searchResultsFieldValues A list of field value objects returned for a specific search. Objects are fieldId, name, value, and the dirty flag.
searchTargetId The Business Object ID or document repository to query.
searchTargetType Either Business Object or document repository.
selectedChangeLimit

The change time frame for the query. For example: 

 { "displayName": "Yesterday", "units": "Days", "value": -1 },
Possible values are based on the unit. In the example above, -1 for the Days unit equals today minus 1 day.

selectedSortByFieldId The fieldID of a field used to sort results.
simpleResultsListItems A list of records returned for a query.
sortByFields A list of pre-defined options available for the search.
sortByOption An option to indicate if sorting is allowed. Use the Option Key to determine if you can change this option.
specificSearchItems A list of options and settings for specific Business Object quick searches.
subtitle The Last Modified Subtitle for a search result record.
targetId The Business Object ID to query.
title The search criteria for a simple text search.
useSortBy A flag to indicate if sorting should be used (true) or not (false).
watermarkText The text provided for the quick search control for specific searches.

Search operations (search item or search result operation responses)

Parameter Operation Usage
allowValuesOnly A flag to indicate that only specified values can be used for a prompt (true) or that any value can be provided (false).
changedOption An indicator that a change limit can be used. Use the Option Key to determine if you can change this option.

Option Key

  • 0 = None (Not selected and cannot select.)
  • 1 = Use (Selected and cannot clear.)
  • 2 = Display (Not selected and can select.)
  • 3 = UseAndDisplay (Selected and can clear.)
childFolders A list of child folders that contain stored queries.
childItems A list of stored queries that are children of a scope.
constraintXml An XML version of properties for a constraint used for a prompt.
customGridDefId The internal ID for the grid used to override field list settings.
default The default value set for a prompt.
defaultSortOrderAscending A flag to indicate the default sort order. True is ascending; false is descending.
exportFormat The format of exported searches:
  • 0 = CSV
  • 1 = Excel
  • 2 = Tab
  • 3 = Word
  • 4 = Custom Separator
  • 5 = Simple JSON
fields A list of fields to return.
filters A set of filters to apply to searches. Each filter includes fieldId, operator, and value.
hasPrompts A flag that indicates that a stored query has prompts.
includeAllFields A flag to include all fields in impromptu search results.
includeSchema A flag to include the table schema of the saved search. If false, results contain the fieldid and field value without field information. Default is false.
isDateRange A flag to indicate that a prompt includes a date range.
listDisplayOption The list display option for a prompt:
  • 0 = Auto
  • 1 = Simple text box
  • 2 = List of values in a combo
  • 3 = List of values in a grid
  • 4 = List of values in a simple list
listReturnFieldId The internal ID for the field returned when a prompt list is a grid.
localizedScopeName A translated scope name based on a user's assigned culture.
parentFolderId The name or internal ID of a folder that contains stored queries.
promptId The internal ID or name for a prompt.
promptName The display name of a prompt.
prompts A list of objects associated with prompts.
promptType The type of prompt:
  • 1 = Text
  • 2 = Number
  • 3 = Date/Time
  • 4 = Logical
  • 5 = Date
  • 6 = Time
promptValue The default value for a prompt.
promptValues For search operation requests, a prompt ID, prompt name, and value. Either prompt ID or prompt name is required. This can be a list of multiple prompts needed for each request.

For search operation responses, a list of values to choose from. Values are not processed at runtime.

searchID The internal ID of a stored query.
searchName The display name of a stored query.
searchResultsFields A list of field schema objects.
searchTerm/searchText A text string used to filter search results.
sortDirection The possible values are:
  • 0 = No sorting
  • 1 = Ascending
  • 2 = Descending
sorting A set of objects used to sort search results.
supportedAssociations A list of Business Objects associated with the Business Object you are querying.
text The text shown in the prompt window.
totalRows The number of records returned by a search.

Security operations (requests or responses)

Parameter Operation Usage
accountLocked A flag to indicate that a user account is locked.
add A flag to indicate if "Add" is granted to a security group for a specific right.
addUserToTeamRequests A list of objects for adding users to teams.
allow A flag to indicate if "Allow" is granted to a security group for a specific right.
applicationtype The type of application to get authentication settings for. Values are RichClient (CSM Desktop Client, BrowserClient, BrowserPortal (CSM Portal), and MobileClient (Cherwell Mobile).
browserClientCustomViewId The internal ID of the Browser Client View assigned to a role.
businessObjectExcludeList The internal IDs for Business Objects that are excluded for a role.
categoryid The internal ID for the security group category.
categoryname The display name for the security group category.
createDateTime The date and time a user account was created.
culture The language code for the culture assigned to a role.
delete A flag to indicate if "Delete" is granted to a security group for a specific right.
departmentMemberEdit A flag to indicate if a department member can edit Business Object records or fields in those records.
departmentMemberView A flag to indicate if a department member can view Business Object records or fields in those records.
edit A flag to indicate if edit rights are granted.
emailAlias The email alias assigned to a team
fieldPermissions A list of rights objects for a security group.
groupid The internal ID for a security group.
groupname The display name for a security group.
image The image assigned to a team.
internalLoginAllowed A flag to indicate if internal authentication is configured for a specified client.
isYesNoRight A flag to indicate that a security group right is either allowed or not allowed.
lastPasswordResetDate The date a user's password was last reset.
lastPasswordResetTime The time a user's password was last reset.
ldapLoginAllowed A flag to indicate if LDAP authentication is configured for a specified client.
dlapRequired A flag to indicate whether Active Directory group membership is required.
managerOfOwnerEdit A flag to indicate if a manager of an owner can edit Business Object records or fields in those records.
managerOfOwnerView A flag to indicate if a manager of an owner can view Business Object records or fields in those records.
nextPasswordResetDate The date on which users are required to change their passwords.
nonScopeOwnerAdd A flag to indicate that users are granted the Add right for items outside of their ownership scope.
nonScopeOwnerDelete A flag to indicate that users are granted the Delete right for items outside of their ownership scope.
nonScopeOwnerEdit A flag to indicate that users are granted the Edit right for items outside of their ownership scope.
nonScopeOwnerView A flag to indicate that users are granted the View right for items outside of their ownership scope.
ownerEdit A flag to indicate if an owner can edit Business Object records or fields in those records.
ownerView A flag to indicate if an owner can view Business Object records or fields in those records.
passwordNeverExpires A flag to indicate whether a user's password expires or not.
primaryBusObId The internal ID of the primary Business Object assigned to a role.
publicid/publicId The public ID used to identify users.
rightId The internal ID for a security group right.
rightName The internal name for a right.
roleId The internal ID for a role.
roleName The display name for a role.
roles A list of objects related to roles.
samlLoginAllowed A flag to indicate if SAML authentication is configured for a specified client.
SecurityGroupId The internal ID for a security group.
securityGroups A list of objects related to security groups.
shortDisplayName The display name for a user.
smartClientCustomViewId The internal ID of the Desktop Client view assigned to a role.
standardRightName The internal name for a right, prepended with the right's category.
teamEdit A flag to indicate if a team member can edit Business Object records or fields in those records.
teamId The internal ID for a team.
teamManagerOfOwnerEdit A flag to indicate if a team manager can edit field in a Business Object record.
teamManagerOfOwnerView A flag to indicate if a team manager can view field in a Business Object record.
teamName The display name for a team.
teams A list of objects related to teams.
teamType The type of team:
  • User = User teams
  • CustomerWorkgroup = Customer workgroups
teamView A flag to indicate if a team member can view Business Object records or fields in those records.
userCannotChangePassword A flag to prevent users from changing their passwords.
userInfoFields A list of objects related to user information fields.
userIsTeamManager A flag to indicate that a user is a manager of a team.
userMustChangePasswordAtNextLogin A flag to require users to change their password when they log in next.
view A flag to indicate if view rights are granted.
viewRunOpen A flag to indicate if Run, View, or Open are granted to a security group for a specific right.
windowsLoginAllowed A flag to indicate if Windows authentication is configured for a specified client.
windowsUserId The Windows login ID for a CSM user.

Service information operations (responses)

Parameter Operation Usage
apiVersion The version of the Cherwell REST API you are using.
csmCulture The default culture for CSM.
csmVersion The CSM version.
systemDateTime The current date and time for the CSM server in UTC format.
systemUtcOffset The UTC offset so the system can transform a date/time.
timeZone The time zone of the CSM Application Server. Data returned is a serialization of the .NET TimeZoneInfo class.

Token operations (requests or responses)

Parameter Operation Usage
.expires The date and time a token expires.
.issued The date and time a token was issued.
access_token The issued access token.
as:client_id The API Client ID used to request a token.
auth_mode The authentication mode to use for requesting access tokens. Options are Internal (for CSM authentication), Windows, LDAP, and SAML.
client_id The API client ID for the client making the token request.
client_secret The API client secret for the native client making the token request. This is only required for native clients.
expires_in The number of seconds before a token expires.
grant_type The type of token being requested: password or refresh token.
refresh_token The refresh token used to grant another access token.
token_type The type of token. Currently, the type is always "bearer".

Type

Parameter Operation Usage
type (Attachments) The type of record attachment:
  • 0 = None: Not applicable to the Cherwell REST API.
  • 1 = File: Linked files.
  • 2 = FileManagerFile: Imported files.
  • 3 = BusOb: Attached Business Objects.
  • 4 = History: Information about the attachment, if available.
  • 5 = Other: Not applicable to the Cherwell REST API.
type (Business Objects) The type of Business Object:
  • All
  • Major
  • Supporting
  • Lookup
  • Groups
type (Fields)/fieldType The type of field (Text, Date/Time, etc.).

Miscellaneous

Parameter Operation Usage
attributes A list of attributes defined for specific fields.
busobname/busObName

The display name for a Business Object type. Examples include:

  • Incident
  • Task
  • Service Cart
categoryDescription - getsecuritygroupcategories Not used by the Cherwell REST API.
dateTimeFormatting For ExportSearchResults only, the format for Date/Time fields. For example: mm/dd/yyyy or dd/mm/yyyy.

Due to other system changes, this parameter has been deprecated.

deleteRequests A list of deleteRequest objects that will be processed.
description The description of an object.
displaytext/displayName The display text for the item.

For example, use the attachment name, which is the display text for an attachment record.

error An error message. (Deprecated in V2 operations.)
errorCode A text string used to indicate a type of error message.
errorMessage An error message.
fieldName The display name of a field.
fields In most cases, set a field parameter, such as fieldId, name, and value.
fieldsList A specific list of fields to request.
fieldValidationErrors A list of objects related to field validation.
fullFieldiD A string containing the internal Business Object ID and internal Field ID.
height For Get Gallery Image operation requests, the height of an icon.
lang Returns localized responses in the specified language.

Language codes must be passed using the en-US format (fr-FR, de-De, etc.). Language codes are not case-sensitive.

locale Returns localized responses (date/time, currency, number formatting) in the specified locale.

Language codes must be passed using the en-US format (fr-FR, de-De, etc.). Language codes are not case-sensitive.

loginId A user's login ID.
mobileClientCustomViewId Not applicable to the Cherwell REST API.
operator A string used to evaluate filters.
pageNumber The page number of the result set to return.
pageSize The number of rows to return per page.
parentBusObPublicId The public ID for the parent Business Object.
parentbusobrecid The record ID for the parent Business Object.
password The password assigned to a user account.
readRequests A list of readRequest objects used to return a batch of items, such as Business Objects or users.
recIdFields The record ID fields specified for a Business Object.
relationshipid The internal Relationship ID for the related Business Object.
scanCode The scan code for a specific Business Object record.
standInKey/oneStepActionStandInKey For Core operations, the internal key for an item derived from its scope, scope owner, and folder.
totalRecords For batch delete operations, the total number of records deleted.
url A URL string.
username A CSM user's Login ID.
value A string used to identify a value or to filter results.
width For Get Gallery Image operation requests, the width of an icon.