Command Reference
Every command a script can issue, what it does and what it needs.
A script issues a command with importer.execute, naming the command and giving it the
arguments below:
importer.execute("CreateDraft", name="Draft 1")
Every command acts somewhere. Unless you say otherwise it acts where the run is pointed, and the commands are grouped below by the kind of place each one acts on. To act somewhere else, give the command a location - see Saying where a command acts.
What each command does
Commands are grouped by where they act, below. This is all of them, in one list.
Command
What it does
Add an image for a project's wiki pages to show.
Add text to the end of a project's wiki page.
Copy one record - a form, an edit check, a record of a type you defined - from another draft into this one.
Add a diagnostic of your own, written in Python, which runs when a draft is checked and reports what it finds against the objects you name.
Add a template which uses the system object relational mapper and Jinja2 template system to create outputs in Word, Excel and other formats
Create an empty draft in a project, as the New Draft page does.
Create one record of an object type, with the values it holds.
Add a property that every draft in this URL can hold.
Add an icon your Organization can use wherever an icon is chosen.
Add a kind of object of your own, such as a Visit or a Country, for this URL to hold records of.
Make one of an object's existing properties part of its unique identifier.
Add a property that every project in this URL can hold.
Add a property to one of this URL's objects, so its records can hold that value.
Add a property that every ticket in this URL can hold.
Replace text in a project's wiki page.
Import every applicable matrix, edit check and derivation from the Standard Library, being those whose prerequisites this draft already satisfies.
Point a draft at the Standard Library it is built from.
Put a form in a folder of a matrix, or take it out.
Show or hide one of this URL's objects, without changing anything it holds.
Write a project's wiki page, creating it if it does not exist.
Change the values of one record a draft already holds.
Change a project's settings and custom properties, as the Edit Project page does.
Commands that act on your Organization
What these create belongs to your whole Organization, so they are available wherever a run is pointed.
CreateIcon
Add an icon your Organization can use wherever an icon is chosen.
Icon names are shared across every Organization, so yours is stored with your Organization's short name in front of it. You give the name without that part and it is added for you - but the stored name is the prefixed one, and that is what any command referring to the icon must use. An Organization called Acme adding 'pencil' gets 'acme-pencil'.
The drawing is refused outright if it carries anything that could do something: a script, a javascript: address, an event handler, a CSS import or external stylesheet, an image, iframe, embed, object or foreignObject element, an animation pointed at an event handler, or a DOCTYPE or entity declaration. A DOCTYPE is the one you are most likely to meet, because some drawing tools put one at the top of every file they export; delete that line and the rest will be accepted.
Anything else the cleaner does not recognise is taken out and the rest is stored, so an icon using style, filter or a fill rule arrives without them and may not look as it did in your file. Check the icon after you create it.
It must be under 50KB and no more than 2000 by 2000.
Argument
Accepts
Required
Default
What it is
Limits
organization_locationwhere the run is pointed
Where the command acts. Leave it out and the command acts where the run is pointed, which must then reach an organization.
must reach an organization
nametext
yes
What the icon is called, in lower case, using letters, numbers, hyphens and underscores. Your Organization's short name and a hyphen are put in front of it for you, and the limit below counts those too, so the name you give has to be shorter by the length of your short name plus one.
at least 1 character; at most 100 characters
svg_contenttext
yes
The drawing itself, as SVG.
at least 1 character
descriptiontext
What the icon is for, to help somebody choosing between icons.
Commands that act on a URL
These shape what a URL can hold: the kinds of object in it and the properties their records carry.
CreatePropertyDefinition
Add a property to one of this URL's objects, so its records can hold that value.
Which arguments apply depends on value_type, and anything belonging to a different type is refused rather than ignored. So text_max_length and text_validation_regex are for text; value_choices for choice, where it is required; set_values and set_separator for set, where set_values is required; numeric_min_value, numeric_max_value and numeric_decimal_places for numeric; and reference_type for reference, where it is required.
Project, CRF Draft and Ticket are not named here. Each has its own command: CreateProjectPropertyDefinition, CreateDraftPropertyDefinition and CreateTicketPropertyDefinition. This command refuses those three names rather than guessing which you meant. A project property and a ticket property cannot be a reference, which is why those two commands offer fewer value types than this one; a draft property offers the same ones.
Argument
Accepts
Required
Default
What it is
Limits
url_locationwhere the run is pointed
Where the command acts. Leave it out and the command acts where the run is pointed, which must then reach a URL.
must reach a URL
applies_totext
yes
The object the property is added to, by name. This is one of the URL's own objects, such as Form or Field or one you have created yourself.
at least 1 character; at most 100 characters
nametext
yes
What the property is called. This is the label people see against it.
at least 1 character; at most 100 characters
activetrue or false
TrueWhether the property is in use. An inactive one keeps what it holds but is not offered for editing.
can_be_copiedtrue or false
TrueWhether the property's value comes along when a record is copied.
descriptiontext
Help text shown with the property, to say what somebody should put in it.
display_orderwhole number
1Where the property sits among the others. Lower numbers come first. This also decides the order of the parts of an object's identifier, so set it here if the property will be added to one. Two properties sharing a display order fall back to whichever was created first.
include_in_agent_contexttrue or false
FalseWhether the property's value is given to agents working on the record.
include_in_compliance_calculationstrue or false
TrueWhether a difference in this property counts when a draft is compared against its Standard Library.
llm_instructiontext
What to tell an agent about this property, when it is given to one.
numeric_decimal_placeswhole number
How many decimal places a number is kept to. Only for value_type numeric.
0 or more
numeric_max_valuenumber
The largest number allowed. Only for value_type numeric, and it cannot be below numeric_min_value.
numeric_min_valuenumber
The smallest number allowed. Only for value_type numeric.
reference_typetext
The object a reference points at, by name. Required when value_type is reference, and refused otherwise.
at most 100 characters
reserved_for_actionstrue or false
FalseWhether the property is set only by actions. People cannot edit one that is.
set_separatortext
|
What the ticked values are joined with when they are stored. Defaults to a vertical bar. Only for value_type set, and it cannot be spaces.
at least 1 character; at most 4 characters
set_valueslist of text
The values somebody may tick, any number of them. Required when value_type is set, and refused otherwise. No value may contain the separator.
show_in_liststrue or false
FalseWhether the property appears as a column when records are listed.
text_max_lengthwhole number
The longest a text value may be. Only for value_type text.
1 or more
text_validation_regextext
A regular expression a text value must match. Only for value_type text.
at most 500 characters
value_choiceslist of text
The values somebody may pick from. Required when value_type is choice, and refused otherwise. Two choices that differ only in case or spacing are not allowed.
value_type
choice,text,reference,html,boolean,uri,color,numeric,date,datetime,set,user
textWhat kind of value the property holds. This decides which of the other arguments apply; the rest are refused.
CreateCustomDiagnostic
Add a diagnostic of your own, written in Python, which runs when a draft is checked and reports what it finds against the objects you name.
The check is Python, and it runs when a draft is checked. Every name in applies_to must already exist on this URL; the category is shared across the application rather than belonging to a URL.
Say which kinds of draft it runs against. rave_linter and vault_linter are separate, and their defaults are not the same: leave both out and you get a diagnostic that runs on Rave drafts and not on Vault ones. Turning both off leaves one that never runs.
Argument
Accepts
Required
Default
What it is
Limits
url_locationwhere the run is pointed
Where the command acts. Leave it out and the command acts where the run is pointed, which must then reach a URL.
must reach a URL
codetext
yes
The check itself, written in Python.
at least 1 character
descriptiontext
yes
What the diagnostic looks for and what somebody should do about a result.
at most 2000 characters
nametext
yes
What the diagnostic is called where its results are listed.
at least 1 character; at most 2000 characters
short_nametext
yes
A short label for the diagnostic, up to 20 characters. Four-digit labels are kept for the built-in diagnostics, so yours cannot be one.
at least 1 character; at most 20 characters
activetrue or false
TrueWhether the diagnostic runs. An inactive one is kept but not used.
applies_tolist of text
The objects the diagnostic reports on, by name. Each must already exist on this URL.
autofixtrue or false
FalseWhether every result can be fixed in one go, rather than one at a time.
categorytext
The category the diagnostic is listed under, by name. Categories are shared across the whole application rather than belonging to a URL, and the one you name must already exist.
at most 255 characters
fixtrue or false
FalseWhether a result offers to fix the thing it found.
fix_input_control
text,textarea
textWhat the person fixing a result types into: a single line, or a larger box.
icontext
boltThe icon shown against the diagnostic: a Font Awesome icon name, without the 'fa-' in front of it. An icon your Organization has added is not one of these.
at most 50 characters
importance
0,1,2
1How serious a result is: 0 for low, 1 for medium, 2 for high.
language
python
pythonThe language the check is written in.
rave_lintertrue or false
TrueWhether the diagnostic runs against Rave drafts.
settings_helptext
Help text shown with the diagnostic's own settings.
tagstext
The kinds of object this diagnostic reports on, separated by commas. Used to group results.
vault_lintertrue or false
FalseWhether the diagnostic runs against Vault drafts.
versiontext
Your own version marker for the check, so a later change can be told apart.
at most 30 characters
CreateDocumentTemplate
Add a template which uses the system object relational mapper and Jinja2 template system to create outputs in Word, Excel and other formats
A template can ask questions before it runs, given as settings. Each setting has a type, and setting_choices belongs only to a choice while multiple belongs only to a draft; anything else is refused rather than ignored.
Two settings on one template may not have names differing only in case, because the template reads them by name.
Argument
Accepts
Required
Default
What it is
Limits
url_locationwhere the run is pointed
Where the command acts. Leave it out and the command acts where the run is pointed, which must then reach a URL.
must reach a URL
nametext
yes
What the template is called where people choose one.
at least 1 character; at most 100 characters
templatetext
yes
The template itself: the markup that says what the produced document contains.
activetrue or false
TrueWhether the template is offered. An inactive one is kept but not shown.
descriptiontext
What the template produces, to help somebody choosing between templates.
is_lockedtrue or false
FalseWhether the template is protected from being edited.
object_typetext
Which object's list the template is offered from, by name. Required when template_scope is Draft Object List, and refused otherwise.
at most 100 characters
settingsblocks of arguments, listed below
Questions put to the person producing a document, whose answers the template can read. Give each one as a block of its own arguments.
template_scope
Draft Home,Project Home,Project Tickets,Draft Object List
Draft HomeWhere in the application the template is offered.
template_type
Word,Excel 2003/2004 SpreadsheetML,Excel 2003/2004 SpreadsheetML with conversion to XLSX,Text,AI Summary
WordWhat kind of document the template produces.
text_extensiontext
The file extension given to the produced file, for template types that do not imply one.
at most 100 characters
Each block of settings takes:
Argument
Accepts
Required
Default
What it is
Limits
display_nametext
yes
What the person producing a document sees this setting called.
at least 1 character; at most 100 characters
nametext
yes
What the template calls this setting when it reads it. Two settings on one template cannot have names that differ only in case.
at least 1 character; at most 100 characters
setting_type
boolean,text,choice,draftyes
What kind of answer the setting takes.
default_valuetext
The answer the setting starts with.
at most 255 characters
descriptiontext
Help text shown with the setting.
at most 2000 characters
display_orderwhole number
1Where this setting sits among the template's others. Lower numbers come first.
multipletrue or false
FalseWhether more than one draft may be chosen. Only for setting_type draft.
requiredtrue or false
FalseWhether the setting must have a value before the document can be generated. Only for setting_type text or draft: a boolean or choice always has one.
setting_choiceslist of text
The answers somebody may pick from. Required when setting_type is choice, and refused otherwise.
CreateDraftPropertyDefinition
Add a property that every draft in this URL can hold.
Which arguments apply depends on value_type, and anything belonging to a different type is refused rather than ignored. So text_max_length and text_validation_regex are for text; value_choices for choice, where it is required; set_values and set_separator for set, where set_values is required; and numeric_min_value, numeric_max_value and numeric_decimal_places for numeric. A draft property may also be a reference, and then reference_type says what it points at.
Argument
Accepts
Required
Default
What it is
Limits
url_locationwhere the run is pointed
Where the command acts. Leave it out and the command acts where the run is pointed, which must then reach a URL.
must reach a URL
nametext
yes
What the property is called. This is the label people see against it.
at least 1 character; at most 100 characters
activetrue or false
TrueWhether the property is in use. An inactive one keeps what it holds but is not offered for editing.
can_be_copiedtrue or false
TrueWhether the property's value comes along when a record is copied.
descriptiontext
Help text shown with the property, to say what somebody should put in it.
display_orderwhole number
1Where the property sits among the others. Lower numbers come first. This also decides the order of the parts of an object's identifier, so set it here if the property will be added to one. Two properties sharing a display order fall back to whichever was created first.
include_in_agent_contexttrue or false
FalseWhether the property's value is given to agents working on the record.
llm_instructiontext
What to tell an agent about this property, when it is given to one.
numeric_decimal_placeswhole number
How many decimal places a number is kept to. Only for value_type numeric.
0 or more
numeric_max_valuenumber
The largest number allowed. Only for value_type numeric, and it cannot be below numeric_min_value.
numeric_min_valuenumber
The smallest number allowed. Only for value_type numeric.
reference_typetext
The object a reference points at, by name. Required when value_type is reference, and refused otherwise.
at most 100 characters
reserved_for_actionstrue or false
FalseWhether the property is set only by actions. People cannot edit one that is.
set_separatortext
|
What the ticked values are joined with when they are stored. Defaults to a vertical bar. Only for value_type set, and it cannot be spaces.
at least 1 character; at most 4 characters
set_valueslist of text
The values somebody may tick, any number of them. Required when value_type is set, and refused otherwise. No value may contain the separator.
show_in_liststrue or false
FalseWhether the property appears as a column when records are listed.
text_max_lengthwhole number
The longest a text value may be. Only for value_type text.
1 or more
text_validation_regextext
A regular expression a text value must match. Only for value_type text.
at most 500 characters
value_choiceslist of text
The values somebody may pick from. Required when value_type is choice, and refused otherwise. Two choices that differ only in case or spacing are not allowed.
value_type
choice,text,reference,html,boolean,uri,color,numeric,date,datetime,set,user
textWhat kind of value the property holds. This decides which of the other arguments apply; the rest are refused.
CreateObjectDefinition
Add a kind of object of your own, such as a Visit or a Country, for this URL to hold records of.
This creates the kind of object, not any records of it. Follow it with CreatePropertyDefinition for each value the records should hold, and CreateObjectIdentifier for the properties that say which record you mean.
The name and the external name must each be unused on this URL, and the name cannot be one of the built-in ones such as Project, CRF Draft or Ticket.
Objects nest one level only: an object can have a parent, but that parent cannot itself have one. parent cannot be changed once the object exists, so decide it here.
Argument
Accepts
Required
Default
What it is
Limits
url_locationwhere the run is pointed
Where the command acts. Leave it out and the command acts where the run is pointed, which must then reach a URL.
must reach a URL
external_nametext
yes
The name used when these objects are imported and exported. It becomes a sheet name in a spreadsheet, so Excel's rules apply: no / \ ? * : [ ] characters, no apostrophe at either end, and not History. It also cannot be the export name of a built-in object, or the name of another sheet the Draft download writes, such as CheckSteps or TG_Rules.
at least 1 character; at most 31 characters
nametext
yes
What one of these objects is called.
at least 1 character; at most 100 characters
plural_nametext
yes
What several of them are called. Used wherever a list of them is shown.
at least 1 character; at most 100 characters
descriptiontext
What this kind of object is for.
display_orderwhole number
1Where this object sits among the others in lists and menus. Lower numbers come first.
has_ordinaltrue or false
FalseWhether these objects are numbered, so they keep an order of their own.
icontext
The icon shown against these objects, by name. A built-in icon by its own name, or one of your Organization's by its prefixed name.
at most 100 characters
identifier_separatortext
|
What the parts of the identifier are joined with, when a record is told apart by more than one property. Defaults to a vertical bar with a space either side.
at most 10 characters
llm_instructiontext
What to tell an agent about this kind of object, when it works on one.
parenttext
The object this one sits inside, by name, if it is a child of another. It cannot be changed afterwards.
at most 100 characters
CreateObjectIdentifier
Make one of an object's existing properties part of its unique identifier.
An object's identifier is the set of properties whose values, concatenated together in their display order, uniquely identify an object of that type. Run this command once for each property that makes up the identifier.
Create the property first. This command adds an existing property to the identifier; it does not create one.
Argument
Accepts
Required
Default
What it is
Limits
url_locationwhere the run is pointed
Where the command acts. Leave it out and the command acts where the run is pointed, which must then reach a URL.
must reach a URL
custom_objecttext
yes
The object whose identifier you are adding to, by name.
at least 1 character; at most 100 characters
propertytext
yes
The property to add to that object's identifier, by name. It must already exist on the object.
at least 1 character; at most 100 characters
CreateProjectPropertyDefinition
Add a property that every project in this URL can hold.
Which arguments apply depends on value_type, and anything belonging to a different type is refused rather than ignored. So text_max_length and text_validation_regex are for text; value_choices for choice, where it is required; set_values and set_separator for set, where set_values is required; and numeric_min_value, numeric_max_value and numeric_decimal_places for numeric.
A project property cannot be a reference. Reference values point at something inside a single draft, so they do not mean anything outside one.
Argument
Accepts
Required
Default
What it is
Limits
url_locationwhere the run is pointed
Where the command acts. Leave it out and the command acts where the run is pointed, which must then reach a URL.
must reach a URL
nametext
yes
What the property is called. This is the label people see against it.
at least 1 character; at most 100 characters
activetrue or false
TrueWhether the property is in use. An inactive one keeps what it holds but is not offered for editing.
can_be_copiedtrue or false
TrueWhether the property's value comes along when a record is copied.
descriptiontext
Help text shown with the property, to say what somebody should put in it.
display_orderwhole number
1Where the property sits among the others. Lower numbers come first. This also decides the order of the parts of an object's identifier, so set it here if the property will be added to one. Two properties sharing a display order fall back to whichever was created first.
include_in_agent_contexttrue or false
FalseWhether the property's value is given to agents working on the record.
llm_instructiontext
What to tell an agent about this property, when it is given to one.
numeric_decimal_placeswhole number
How many decimal places a number is kept to. Only for value_type numeric.
0 or more
numeric_max_valuenumber
The largest number allowed. Only for value_type numeric, and it cannot be below numeric_min_value.
numeric_min_valuenumber
The smallest number allowed. Only for value_type numeric.
reserved_for_actionstrue or false
FalseWhether the property is set only by actions. People cannot edit one that is.
set_separatortext
|
What the ticked values are joined with when they are stored. Defaults to a vertical bar. Only for value_type set, and it cannot be spaces.
at least 1 character; at most 4 characters
set_valueslist of text
The values somebody may tick, any number of them. Required when value_type is set, and refused otherwise. No value may contain the separator.
show_in_liststrue or false
FalseWhether the property appears as a column when records are listed.
text_max_lengthwhole number
The longest a text value may be. Only for value_type text.
1 or more
text_validation_regextext
A regular expression a text value must match. Only for value_type text.
at most 500 characters
value_choiceslist of text
The values somebody may pick from. Required when value_type is choice, and refused otherwise. Two choices that differ only in case or spacing are not allowed.
value_type
choice,text,html,boolean,uri,color,numeric,date,datetime,set,user
textWhat kind of value the property holds. This decides which of the other arguments apply; the rest are refused.
CreateTicketPropertyDefinition
Add a property that every ticket in this URL can hold.
Which arguments apply depends on value_type, and anything belonging to a different type is refused rather than ignored. So text_max_length and text_validation_regex are for text; value_choices for choice, where it is required; set_values and set_separator for set, where set_values is required; and numeric_min_value, numeric_max_value and numeric_decimal_places for numeric.
A ticket property cannot be a reference. Reference values point at something inside a single draft, so they do not mean anything outside one.
Argument
Accepts
Required
Default
What it is
Limits
url_locationwhere the run is pointed
Where the command acts. Leave it out and the command acts where the run is pointed, which must then reach a URL.
must reach a URL
nametext
yes
What the property is called. This is the label people see against it.
at least 1 character; at most 100 characters
activetrue or false
TrueWhether the property is in use. An inactive one keeps what it holds but is not offered for editing.
descriptiontext
Help text shown with the property, to say what somebody should put in it.
display_orderwhole number
1Where the property sits among the others. Lower numbers come first. This also decides the order of the parts of an object's identifier, so set it here if the property will be added to one. Two properties sharing a display order fall back to whichever was created first.
include_in_agent_contexttrue or false
FalseWhether the property's value is given to agents working on the record.
llm_instructiontext
What to tell an agent about this property, when it is given to one.
numeric_decimal_placeswhole number
How many decimal places a number is kept to. Only for value_type numeric.
0 or more
numeric_max_valuenumber
The largest number allowed. Only for value_type numeric, and it cannot be below numeric_min_value.
numeric_min_valuenumber
The smallest number allowed. Only for value_type numeric.
reserved_for_actionstrue or false
FalseWhether the property is set only by actions. People cannot edit one that is.
set_separatortext
|
What the ticked values are joined with when they are stored. Defaults to a vertical bar. Only for value_type set, and it cannot be spaces.
at least 1 character; at most 4 characters
set_valueslist of text
The values somebody may tick, any number of them. Required when value_type is set, and refused otherwise. No value may contain the separator.
show_in_liststrue or false
FalseWhether the property appears as a column when records are listed.
text_max_lengthwhole number
The longest a text value may be. Only for value_type text.
1 or more
text_validation_regextext
A regular expression a text value must match. Only for value_type text.
at most 500 characters
value_choiceslist of text
The values somebody may pick from. Required when value_type is choice, and refused otherwise. Two choices that differ only in case or spacing are not allowed.
value_type
choice,text,html,boolean,uri,color,numeric,date,datetime,set,user
textWhat kind of value the property holds. This decides which of the other arguments apply; the rest are refused.
SetObjectDefinitionVisible
Show or hide one of this URL's objects, without changing anything it holds.
Hiding an object takes it out of the places people choose objects from, except for the lists of a parent object's children, where it still appears. The records it already holds are untouched, and showing it again brings them back into view.
Use this to build an object up over several commands and only show it once it is complete.
Argument
Accepts
Required
Default
What it is
Limits
url_locationwhere the run is pointed
Where the command acts. Leave it out and the command acts where the run is pointed, which must then reach a URL.
must reach a URL
custom_objecttext
yes
The object to show or hide, by name.
at least 1 character; at most 100 characters
visibletrue or false
yes
True to show the object, false to hide it.
Commands that act on a project
AddWikiImage
Add an image for a project's wiki pages to show.
Pages show the image by its token, written as , in a page set by SetWikiPage or AppendToWikiPage. Generate a new random token for each image: a token used by an image anywhere else is refused. Giving the same token again for the same project adds nothing and keeps the image already there, so giving the same image again leaves one copy, and a changed image needs a new token.
The image is checked for malware and re-encoded once the commands are applied, as an image pasted into the wiki is, and shows as being checked until then. An image that cannot be stored once the commands are applied is named in the apply's result; add it again with the same token.
The image travels as base64 inside the run, which counts towards the 10,000,000 characters a run may record. That allows about 7 MB of images in one run, less whatever the pages take, so scale a large image down before encoding it.
Argument
Accepts
Required
Default
What it is
Limits
project_locationwhere the run is pointed
Where the command acts. Leave it out and the command acts where the run is pointed, which must then reach a project.
must reach a project
datatext
yes
The image file, a PNG, JPEG or GIF, as base64. Line breaks in it are ignored.
tokenUUID
yes
The image's identifier: a new random UUID chosen by the script. A page shows the image by referring to /image/<token>, as in .
AppendToWikiPage
Add text to the end of a project's wiki page.
The text is added after a blank line, so it starts a paragraph or section of its own, and the page gets a new version holding the result.
The page must already exist: a name that matches no page is refused rather than starting a page with only its last part. Create it first with SetWikiPage.
Argument
Accepts
Required
Default
What it is
Limits
project_locationwhere the run is pointed
Where the command acts. Leave it out and the command acts where the run is pointed, which must then reach a project.
must reach a project
contenttext
yes
The Markdown to add to the end of the page, after a blank line.
at least 1 character
titletext
yes
The page's name. Case does not count as a difference, so this finds a page whatever case it was created in. Leading and trailing spaces are dropped and a / becomes an _, as the wiki editor does.
CreateDraft
Create an empty draft in a project, as the New Draft page does.
The draft arrives empty apart from the SUBJECT folder every draft is made with. To fill it, follow this command with CopyDraftObject, LinkDraftToLibrary and ImportRelatedObjects.
The project is where the command acts, so it comes from where the run is pointed unless the command is given a project_location.
Argument
Accepts
Required
Default
What it is
Limits
project_locationwhere the run is pointed
Where the command acts. Leave it out and the command acts where the run is pointed, which must then reach a project.
must reach a project
nametext
yes
What the new draft is called. A project cannot hold two drafts of the same name, and case does not count as a difference.
at least 1 character; at most 255 characters
EditWikiPage
Replace text in a project's wiki page.
The text to replace is found by exact match, never by guessing: if the page does not contain it, or contains it more than once, the command is refused and says which. Include enough of the surrounding text to make it match once, or set replace_all to replace every occurrence. Occurrences that overlap count separately, and cannot all be replaced.
The text is matched against the page as it is when the commands are applied, not as it was when the script ran. An edit is refused if the text is no longer there or, without replace_all, is now there more than once; with replace_all, every occurrence there by then is replaced. The page gets a new version holding the result.
Argument
Accepts
Required
Default
What it is
Limits
project_locationwhere the run is pointed
Where the command acts. Leave it out and the command acts where the run is pointed, which must then reach a project.
must reach a project
new_texttext
yes
What replaces it. Empty to delete the text.
old_texttext
yes
The text to replace, exactly as the page holds it: case, spaces and line breaks all count.
at least 1 character
titletext
yes
The page's name. Case does not count as a difference, so this finds a page whatever case it was created in. Leading and trailing spaces are dropped and a / becomes an _, as the wiki editor does.
replace_alltrue or false
FalseReplace every occurrence. Without it, text found more than once is refused.
SetWikiPage
Write a project's wiki page, creating it if it does not exist.
The page gets a new version holding the content given, and its earlier versions stay in its history. Content the page already holds adds no version.
To build a page in parts, set the first part with this command and add the rest with AppendToWikiPage. Building it again that way adds a version for every part, since the first part differs from the whole page.
Argument
Accepts
Required
Default
What it is
Limits
project_locationwhere the run is pointed
Where the command acts. Leave it out and the command acts where the run is pointed, which must then reach a project.
must reach a project
contenttext
yes
The whole of the page, in the wiki's Markdown. It replaces what the page holds.
titletext
yes
The page's name. Case does not count as a difference, so this finds a page whatever case it was created in. Leading and trailing spaces are dropped and a / becomes an _, as the wiki editor does.
UpdateProject
Change a project's settings and custom properties, as the Edit Project page does.
The settings are the ones on the Edit Project page, named as the project's fields are named: ProjectName, ProjectDescription, ProtocolName, view_all, active, send_standards_workflow_emails, wiki_page, run_on_url, run_on_project, run_on_protocol_id, run_on_site, run_on_environment, run_on_environment_name, run_on_client, run_on_study_group, uat_subject_name_format, default_unknown_day, default_unknown_month, default_unknown_year, default_role_for_uat, tca_instructions. view_all, active and send_standards_workflow_emails take True or False. wiki_page takes the name of one of the project's wiki pages, or nothing to show no page. Whether a project is a Standard Library cannot be changed from a script.
A setting or property is held to the rules the page holds it to. A project's name is unique in its URL whatever its case, and on a Rave URL the test case settings cannot be left empty. A custom property is given a value its definition accepts, and a user by their username. Giving a custom property nothing removes its value. One reserved for Actions cannot be set, and an inactive one can only be changed or removed where the project already has a value for it.
Rules that read a project's custom properties are checked again once the run is applied, once for every project whose properties changed rather than once per command.
Renaming a project takes effect for the rest of the run, so a command after it that names the project by its old name is refused, and nothing in the run is applied. Name it by its new one instead, with importer.context.location.with_project("New name").
Argument
Accepts
Required
Default
What it is
Limits
project_locationwhere the run is pointed
Where the command acts. Leave it out and the command acts where the run is pointed, which must then reach a project.
must reach a project
attributestext, number or date; true or false for a true/false attribute
yes
The settings and custom properties to change, by name, and the value each is given. A setting is named as the project's field is named, and a custom property by its own name; case does not matter. Anything not named is left as it is.
at least 1 character
Commands that act on a draft
These work on the contents of one draft, and two of them bring things into it from somewhere else.
CopyDraftObject
Copy one record - a form, an edit check, a record of a type you defined - from another draft into this one.
Say which kind of record with type, and which one with identifier. What the identifier is depends on the kind, because each kind is told apart by its own value: a Form or a Folder by its OID, an Edit Check by its check name, a Derivation by its derivation name, a Custom Function by its function name, a Matrix by its OID, a Data Dictionary or Unit Dictionary by its name, a Test Case or Standard Rule by its name, and a record of a type you defined by its identifier. Case does not matter in either.
The whole record is copied, with whatever it needs to work. A Form arrives with its Fields and the data dictionaries those Fields use, a Matrix with the Folders and Forms its rows name, a Data Dictionary or Unit Dictionary with its entries, and a record of a type you defined with the records inside it. There is no way to copy part of a record: to make something with only the values you choose, use CreateDraftObject instead.
A record the target draft already holds under that identifier is left alone, whatever kind it is: the run says so and copies nothing. So a script can be run again safely, and a script that copies a list of records can have records added to the list and be run again to bring only the new ones. Nothing is ever overwritten, which also means a record already there is not refreshed from the source - to take a changed record, delete the one in the draft first.
A Field sits inside a Form, and a record of a type you defined may sit inside a record of another type. Either one names what it belongs to with parent_identifier, and that one identifier is used at both ends: the record is looked for under a parent of that identifier in the source draft, and the copy is placed under the target draft's record of the same identifier. So the parent has to be in the target draft already - copy it first, or copy it whole and the records inside it come with it. Naming a parent for a kind that does not sit inside anything is refused rather than ignored. A copy is refused if a Form, Folder, data dictionary or unit dictionary it would bring is in the target draft under the same name in another case, because the copy would add a second one beside it.
Copies of one kind from one draft that come one after another in the list are made together, up to 100 at a time. Made together, a Folder is placed inside the Folder it sits in and a Form is linked to its Link Form whichever of the two is copied first. Otherwise the Folder it sits in, or the Form it links to, has to be copied before it, or the copy is left without one.
The source draft must allow its objects to be imported, and you must be able to see it. A draft cannot copy a record from itself, so this always brings something in from somewhere else. The source is named rather than taken from the Standard Library link, so a script can copy from any draft it is allowed to read.
A Standard Rule is copied only into a library's draft. Lab Settings cannot be copied, and neither can a kind of record kept in step with a connected system, or a record whose kind holds records of one. Those are refused by name.
Argument
Accepts
Required
Default
What it is
Limits
target_draft_locationwhere the run is pointed
Where the command acts. Leave it out and the command acts where the run is pointed, which must then reach a draft.
must reach a draft
identifiertext
yes
Which record to copy, by whatever the type is told apart by in the source draft - a Form or Folder by its OID, an Edit Check by its check name, a Custom Function by its function name, a record of a type you defined by its identifier. Case does not matter.
at least 1 character; at most 2000 characters
source_draft_locationyes
The draft to copy the record from. Where it is copied to is target_draft_location. This one must be the location of a draft the script is holding, built with Location.from_object, rather than written out from names.
typetext
yes
The kind of record to copy, by the name the object type is given on this URL. Case does not matter.
at least 1 character; at most 100 characters
parent_identifiertext
For a type whose records sit inside another, the identifier of the record this one belongs to - a Field names the Form it is on, and a record of a type you defined that sits inside another names the record above it. The target draft has to hold that record already. Required for such a type and refused for one that stands on its own.
at most 2000 characters
CreateDraftObject
Create one record of an object type, with the values it holds.
The object type must be one defined on this URL, a dictionary entry, or a step or action. A type somebody defined there, and Form, Field, Folder, Matrix, Custom Function, Test Case, Data Dictionary, Unit Dictionary, Edit Check, Derivation and Standard Rule, can have records created this way, and so can the entries of a dictionary and the steps and actions of an Edit Check or a Derivation. The other built-in types - Lab Setting and the rest - are refused by name until each one is supported, and a type kept in step with a connected system is always refused.
On a Designer URL, a column of a Form or a Field that applies only to Classic Rave stops the apply if it is given a value, and is left empty on the record. A blank value for it sets nothing, as a blank value does anywhere.
Creating a Test Case needs the Manage Tests permission, which is what the Test Case editor asks for. Every other record needs Edit Objects.
The attributes are the properties defined for the object type, named as they are named there. An attribute the type does not have stops the apply rather than being ignored, because a misspelled name would otherwise silently lose a column of a spreadsheet. A value has to be one its property accepts, so a choice has to be one of the choices and a date has to read as a date.
Two attributes refer to something rather than holding text, and both are named the way a person would write them. A reference names the record it points at by that record's identifier, and must name one in this same draft. A user attribute names somebody by their username.
A record of an object type that sits inside another names its parent with parent_identifier. Create the parents first: the parent has to be there when the child is created. If the draft holds two records answering to that identifier the command stops, rather than choosing one.
The identifier of the new record is worked out from the values, as it is everywhere else, so a record the draft already holds under that identifier is refused. That comparison needs an identifier with no question mark in it. A record that leaves out one of the attributes its object type is told apart by is still created, named with a question mark in place of that value, which is what the editor does with the same input. A question mark written as part of a value counts the same way, and so does an object type told apart by nothing at all. Records named like that are not compared, so two of them are both created - check the key column in the script if that matters.
A Field names the OID of its Form in parent_identifier, goes on the end of it, and is checked as the Form editor checks it: its own attributes together, its FieldOID and DraftFieldName against the rest of the Form, its VariableOID against every Field of the draft using it, and a log Field against the Form's LogDirection. A dictionary is named by its name. On a Classic URL a label is a Text Field with no VariableOID and no DataFormat; on a Designer URL it is ControlType Label, and a Field holding data with no VariableOID is given Designer's, made from the Form OID and the FieldOID. Fields created one after another for the same Form are checked and written together, and the Form saved once; if one is refused, none is created.
A Matrix is created empty, and is not made the draft's default matrix. Its Maximum is a whole number from 0 to 9999, and 0 if not given. Which folder/form cells it holds is set afterwards with SetMatrixFolderForm, one command per cell.
A Data or Unit Dictionary is created empty. Each entry is then created with type Data Dictionary Entry or Unit Dictionary Entry, naming the dictionary by its name in parent_identifier, and an entry can be added to any dictionary in the draft. Its Coded Data or Coded Unit may not already be in that dictionary, compared with its case. A Unit Dictionary Entry needs all four constants, except the one given StandardUnit, whose constants are 1, 1, 0 and 0 unless given. A dictionary has one Standard Unit, so marking a second is refused, and no other entry may have the Standard Unit's Unit String.
An Edit Check or a Derivation is created as an ALS workbook holds it: the check or derivation first, then each of its steps with type Check Step or Derivation Step and each of a check's actions with type Check Action, naming it by its name in parent_identifier. They are added in the order the commands come in. A step or action naming a folder, form, field, custom function or matrix the draft does not have is refused, and so is anything else the editor's QuickEdit would refuse in it. Its whole logic can be given at once instead, with QuickEdit or CQL: QuickEdit is the text the editor's QuickEdit tab shows, and on an Edit Check it holds the actions too, while CQL is the logic alone. Either one is checked as the editor checks it. A QuickEdit's first line names the record and gives its settings, so the name and settings columns may be left out, and one given that says something different from the QuickEdit is refused. A Derivation's variable is given by its FolderOID, FormOID, FieldOID, VariableOID, RecordPosition and repeat number columns, or by its QuickEdit, and a draft may have one Derivation for each variable. A check or derivation whose steps do not yet make sense, or which has no actions yet, is created with that error, because the commands that complete it may come later. The ones still incomplete when every command has been applied are listed then.
A Standard Rule can be created only in a library draft. Its RuleType and ObjectType are written by name, as the TG_Rules sheet writes them, and it is checked as the rule editor checks it. A rule not given an Identifier is given the next free one. Saving a rule recalculates every draft linked to the library, so Standard Rules created one after another are checked and written together, up to 100 at a time, with one recalculation for each group. If one is refused, none is created.
A record of a numbered object type goes on the end. Where it sits among the others cannot be chosen from a script, because putting one in the middle means renumbering the records already there.
Argument
Accepts
Required
Default
What it is
Limits
draft_locationwhere the run is pointed
Where the command acts. Leave it out and the command acts where the run is pointed, which must then reach a draft.
must reach a draft
attributestext, number or date; true or false for a true/false attribute
yes
The values the record holds, keyed by the name of the attribute each one is for. For a type somebody defined, the attributes are the properties defined for it, so they are the same boxes a person filling the form in would see, and a record needs at least one value. For a Form, a Field, a Folder, a Matrix or a Custom Function they are the columns that type has, named as the ALS workbook names them, together with any properties added to it on this URL. A Form, a Folder or a Matrix has to be given an OID and a name, a Field a FieldOID and a DraftFieldName, and a Custom Function a name and its source code. On a Designer URL a column that applies only to Classic Rave, such as a Form's IsTemplate or a Field's DraftFieldNumber, cannot be given a value. A Test Case takes Name, Script, IsTemplate and Priority, and has to be given a name and a script. A Data Dictionary takes DataDictionaryName and a Unit Dictionary UnitDictionaryName. A Data Dictionary Entry takes CodedData, UserDataString and Specify, and a Unit Dictionary Entry CodedUnit, UnitString, ConstantA, ConstantB, ConstantC, ConstantK and StandardUnit. An Edit Check takes CheckName, CheckActive, BypassDuringMigration, NeedsRetesting, RetestingReason, CopySource, QuickEdit and CQL, and has to be given a CheckName or a QuickEdit. A Derivation takes DerivationName, Active, BypassDuringMigration, AllVariablesInFolders, AllVariablesInFields, FolderOID, FormOID, FieldOID, VariableOID, RecordPosition, FormRepeatNumber, FolderRepeatNumber, NeedsRetesting, RetestingReason, CopySource, QuickEdit and CQL, and has to be given a DerivationName and the variable it sets, or a QuickEdit. A Check Step, a Check Action and a Derivation Step take the columns of the CheckSteps, CheckActions and DerivationSteps sheets, less the name of the record they belong to and the StepOrdinal, and a Check Action has to be given an ActionType. A Standard Rule takes the columns of the TG_Rules sheet - Identifier, Logic, RuleType, ObjectType, ObjectIdentifier, ObjectIdentifierIsWildcard, AttributeName, AttributeValue, ValueAttributeIsWildcard, Description, Active and Priority - and has to be given a RuleType, an ObjectType and an ObjectIdentifier. Case does not matter in a name, and a blank value sets nothing. A value may be a number or a date as well as text, and is stored the way the attribute stores that kind of value. True or False is taken only by a true/false attribute.
typetext
yes
The kind of record to create, by the name the object type is given on this URL, or Data Dictionary Entry, Unit Dictionary Entry, Check Step, Check Action or Derivation Step. Case does not matter.
at least 1 character; at most 100 characters
parent_identifiertext
For an object type that sits inside another, the identifier of the record this one belongs in, which for a Field is the OID of its Form. The parent has to exist already, so create the parents first. Required for such a type and refused for one that has no parent.
at most 2000 characters
LinkDraftToLibrary
Point a draft at the Standard Library it is built from.
The library must be a draft in a Standard Library project on a URL of the same kind, and it must allow its objects to be imported. A draft cannot be its own library.
Linking is not just a label. Everything in the draft is marked as needing its compliance against the library worked out again, and that recalculation is started. A draft with a library is also what ImportRelatedObjects reads to decide what it can bring in, so link before you use that command.
Argument
Accepts
Required
Default
What it is
Limits
target_draft_locationwhere the run is pointed
Where the command acts. Leave it out and the command acts where the run is pointed, which must then reach a draft.
must reach a draft
library_draft_locationyes
The library draft to point this draft at. The draft being pointed is the one the command acts on. This one must be the location of a draft the script is holding, built with Location.from_object, rather than written out from names.
SetMatrixFolderForm
Put a form in a folder of a matrix, or take it out.
One command sets one cell of the matrix grid. The matrix, the folder and the form all have to be in the draft already, so create them first.
Setting a cell to what it already is changes nothing and records nothing. A cell that does change is recorded on the matrix's history, and does what saving the Matrices grid does: labels that a change to the matrix removes are removed, and the URL's auto actions run for the matrix and for the edit checks that add or merge it.
Needs the Edit Objects permission, which is what the Matrices grid asks for.
Argument
Accepts
Required
Default
What it is
Limits
draft_locationwhere the run is pointed
Where the command acts. Leave it out and the command acts where the run is pointed, which must then reach a draft.
must reach a draft
folder_oidtext
yes
The OID of the folder, which is the column of the cell. SUBJECT is a folder here like any other. Case does not matter.
at least 1 character; at most 2000 characters
form_oidtext
yes
The OID of the form, which is the row of the cell. Case does not matter.
at least 1 character; at most 2000 characters
matrix_oidtext
yes
The OID of the matrix. Case does not matter.
at least 1 character; at most 2000 characters
ontrue or false
yes
True to put the form in that folder of the matrix, false to take it out.
UpdateDraftObject
Change the values of one record a draft already holds.
Any record CreateDraftObject can create can be changed this way: a record of a type somebody defined on this URL, a Form, Field, Folder, Matrix, Custom Function, Test Case, Data Dictionary, Unit Dictionary, Edit Check, Derivation or Standard Rule, an entry of a dictionary, and a step or action of an Edit Check or Derivation. A Lab Setting is refused by name.
The record is named by its identifier, as CopyDraftObject names one, and one inside another by its parent's identifier too. A dictionary entry is named by its code, with its case, because two entries can differ only in case. A step or action is named by its place in its check or derivation, counted from 1, as the editor lists them. Only the attributes named are changed. The values are the ones CreateDraftObject takes, and are held to the same rules, and to the editor's for a record that already exists: a Folder cannot be made a parent of itself, the SUBJECT folder cannot be changed, and a Unit Dictionary keeps one Standard Unit, which can be moved to another entry but not taken away. Changing a Test Case needs the Manage Tests permission, and every other record Edit Objects.
A QuickEdit given to an Edit Check replaces its steps and its actions, as the QuickEdit editor does, and CQL replaces its steps and keeps its actions, as the CQL editor does. A QuickEdit given to a Derivation replaces its logic and the variable it sets, and CQL replaces its logic and keeps the variable. A QuickEdit has to hold steps, and a name, active or bypass value given with it has to agree with its first line. Changing one step or action keeps the others as they were.
An attribute given nothing is cleared: a custom property loses its value, and a column is emptied. A column the record cannot be without, and one that is True or False, cannot be cleared. A custom property reserved for Actions cannot be set, and an inactive one can only be changed or removed where the record already has a value for it. A record of a type somebody defined has to keep at least one value.
A record's identifier can be changed, as long as no other record of its type in the draft has the new one, and a Field's Variable OID too. Checks and derivations naming the old identifier are updated as they are when it is changed in the editor, but as the command is applied rather than afterwards, so a command after it names the record by its new identifier, and a script can rename several records, or one record twice, or swap two names over. A rename is refused while a rename of anything in the draft made outside the script, such as in the editor, is still updating what names it, and so is any change to an Edit Check, a Derivation, their steps or actions, or a Field's Variable OID, because saving those rewrites what they name.
The change is recorded on the record's history, against the person applying the script, with the names of the attributes that changed. A change to a dictionary entry, step or action is recorded on its parent's history, naming the entry by its code or the step or action by its place. A command that leaves every value as it was changes nothing and records nothing. As in the editor, the labels the change takes away are removed, and the auto actions for the record are run.
Changes to the Fields of one Form, the entries of one dictionary, or the steps or the actions of one check or derivation, made one after another, are checked and written together, up to 100 at a time, and the parent is saved once for them, as its editor saves it: its history records the change, and its labels and auto actions are dealt with once. If one is refused, none of them is made. Changes to Standard Rules made one after another are written together the same way, and the Drafts linked to the library are recalculated once for them. A change to what a Field, an entry or a Standard Rule is named by is written on its own, so the commands after it name it by its new name, and so is marking an entry as its Unit Dictionary's Standard Unit.
Argument
Accepts
Required
Default
What it is
Limits
draft_locationwhere the run is pointed
Where the command acts. Leave it out and the command acts where the run is pointed, which must then reach a draft.
must reach a draft
attributestext, number or date; true or false for a true/false attribute
yes
The attributes to change, by name, and the value each is given. They are named as CreateDraftObject names them: a column as the ALS workbook heads it, and a custom property by its own name; case does not matter. Anything not named is left as it is, and an attribute given nothing is cleared.
at least 1 character
identifiertext
yes
Which record to change, by whatever the type is told apart by - a Form, Folder, Matrix or Field by its OID, a Custom Function by its function name, a dictionary, Edit Check, Derivation or Test Case by its name, a Standard Rule or a record of a type you defined by its identifier. Case does not matter, except for a dictionary entry, which is named by its code exactly. A step or action is named by its place in its check or derivation, counted from 1.
at least 1 character; at most 2000 characters
typetext
yes
The kind of record to change, by the name the object type is given on this URL. Case does not matter.
at least 1 character; at most 100 characters
parent_identifiertext
For a type whose records sit inside another, the identifier of the record this one is in: a Field's Form by its OID, an entry's dictionary, or a step's or action's check or derivation, by its name. Required for such a type and refused for one that stands on its own.
at most 2000 characters