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:
|
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
|
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: 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
|
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:
|
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:
|
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:
|
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:
|
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:
|
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:
|
type (Business Objects) | The type of Business Object:
|
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:
|
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. |