| Argument | Description | Types / Required |
|---|
| dataId | The resource ID returned by Data.open, or a dictionary name. | number, string
recommended |
| case | The case content. | object
required |
| replace | Details about where to write the case in the data source if overwriting an existing case. | object
not required |
The
Data.writeCase action writes a case to a
data source. The
case object must be specified in the form of its
JSON representation. Warnings or errors processing the case content will be reported as error messages or logged to
console.log in the JavaScript environment.
The data source is identified using
dataId. If specified as a string, it references the data source that is connected to a dictionary that is part of an application. If specified as a number, it is processed as a
resource ID returned by
Data.open. This typically references non-application data sources. While optional, this should generally be specified explicitly. (If there is only one data source open, the resource ID can be calculated implicitly.)
By default, if the case to be written has a key that matches one of a non-deleted case in the data source, that case will be replaced. This is the same behavior that
writecase uses when writing cases to external dictionaries.
If you want to replace a specific case, you can use the
replace argument. The case is specified by using one of the
data source case identifiers:
- key: When specifying a key (case IDs), only non-deleted cases are matched.
- uuid: Specifying a case's UUID allows matching on all cases, including deleted cases. Note that not all data sources use UUIDs.
- position: Identification by the "location" of the case in the data source also matches on all cases. Note that the position value can change when the data source is modified.
One of these case identifiers must be specified. If multiple identifiers are specified, uuid is prioritized over position, which is prioritized over key.
If replacing a case would result in multiple non-deleted cases sharing the same key, an exception is thrown if the data source does not
support duplicate cases.
Note that if the case's
"deleted" flag is set to
"true", the case is written as deleted. Some data sources write such cases marked as deleted (e.g.,
CSPro DB), while other data sources will treat this as if
Data.deleteCase were called on the case (e.g.,
Text).
When known, the action returns the
position of the case as written in the data source. Otherwise, the action returns undefined.
The action throws an exception if any of its arguments are not specified in a valid form, or if:
- The data source ID is not valid.
- The data source was not opened in read and write mode.
- The case does not include records that are required.
- A case was specified using replace and it does not exist in the data source.
- The case, if written, would result in duplicate cases when not supported by the data source.
- There is an error interacting with the data source.
const dataId = /* retrieved from a call to CS.Data.open */;
// read a case
const caseData = CS.Data.readCase({
dataId: dataId,
key: "010107300710580051"
});
// write the case as verified
caseData.verified = true;
CS.Data.writeCase({
dataId: dataId,
case: caseData
});
const dataId = /* retrieved from a call to CS.Data.open */;
// read a case and modify the two-digit ID item PROVINCE from 1 -> 99
const keyToModify = "010107500210560041";
const caseData = CS.Data.readCase({
dataId: dataId,
key: keyToModify
});
caseData.SURVEY_LEVEL.PROVINCE.code = 99;
// this writes the case using the key 990107500210560041;
// if a case with that key already exists, it is overwritten;
// after this action, there are cases with keys 010107500210560041 and 990107500210560041
CS.Data.writeCase({
dataId: dataId,
case: caseData
});
// alternatively, this replaces the case that was read;
// after this action, the case with key 010107500210560041 does not exist
// but a case with key 990107500210560041 does
CS.Data.writeCase({
dataId: dataId,
case: caseData,
replace: {
key: keyToModify
}
});