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
AddWikiImage	Add an image for a project's wiki pages to show.
AppendToWikiPage	Add text to the end of a project's wiki page.
CopyDraftObject	Copy one record - a form, an edit check, a record of a type you defined - from another draft into this one.
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.
CreateDocumentTemplate	Add a template which uses the system object relational mapper and Jinja2 template system to create outputs in Word, Excel and other formats
CreateDraft	Create an empty draft in a project, as the New Draft page does.
CreateDraftObject	Create one record of an object type, with the values it holds.
CreateDraftPropertyDefinition	Add a property that every draft in this URL can hold.
CreateIcon	Add an icon your Organization can use wherever an icon is chosen.
CreateObjectDefinition	Add a kind of object of your own, such as a Visit or a Country, for this URL to hold records of.
CreateObjectIdentifier	Make one of an object's existing properties part of its unique identifier.
CreateProjectPropertyDefinition	Add a property that every project in this URL can hold.
CreatePropertyDefinition	Add a property to one of this URL's objects, so its records can hold that value.
CreateTicketPropertyDefinition	Add a property that every ticket in this URL can hold.
EditWikiPage	Replace text in a project's wiki page.
ImportRelatedObjects	Import every applicable matrix, edit check and derivation from the Standard Library, being those whose prerequisites this draft already satisfies.
LinkDraftToLibrary	Point a draft at the Standard Library it is built from.
SetMatrixFolderForm	Put a form in a folder of a matrix, or take it out.
SetObjectDefinitionVisible	Show or hide one of this URL's objects, without changing anything it holds.
SetWikiPage	Write a project's wiki page, creating it if it does not exist.

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_location	location		where 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
name	text	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_content	text	yes		The drawing itself, as SVG.	at least 1 character
description	text			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_location	location		where 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_to	text	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
name	text	yes		What the property is called. This is the label people see against it.	at least 1 character; at most 100 characters
active	true or false		True	Whether the property is in use. An inactive one keeps what it holds but is not offered for editing.
can_be_copied	true or false		True	Whether the property's value comes along when a record is copied.
description	text			Help text shown with the property, to say what somebody should put in it.
display_order	whole number		1	Where 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_context	true or false		False	Whether the property's value is given to agents working on the record.
include_in_compliance_calculations	true or false		True	Whether a difference in this property counts when a draft is compared against its Standard Library.
llm_instruction	text			What to tell an agent about this property, when it is given to one.
numeric_decimal_places	whole number			How many decimal places a number is kept to. Only for value_type numeric.	0 or more
numeric_max_value	number			The largest number allowed. Only for value_type numeric, and it cannot be below numeric_min_value.
numeric_min_value	number			The smallest number allowed. Only for value_type numeric.
reference_type	text			The object a reference points at, by name. Required when value_type is reference, and refused otherwise.	at most 100 characters
reserved_for_actions	true or false		False	Whether the property is set only by actions. People cannot edit one that is.
set_separator	text		|	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_values	list 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_lists	true or false		False	Whether the property appears as a column when records are listed.
text_max_length	whole number			The longest a text value may be. Only for value_type text.	1 or more
text_validation_regex	text			A regular expression a text value must match. Only for value_type text.	at most 500 characters
value_choices	list 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, email, uri, color, numeric, date, datetime, set, user		text	What 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_location	location		where 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
code	text	yes		The check itself, written in Python.	at least 1 character
description	text	yes		What the diagnostic looks for and what somebody should do about a result.	at most 2000 characters
name	text	yes		What the diagnostic is called where its results are listed.	at least 1 character; at most 2000 characters
short_name	text	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
active	true or false		True	Whether the diagnostic runs. An inactive one is kept but not used.
applies_to	list of text			The objects the diagnostic reports on, by name. Each must already exist on this URL.
autofix	true or false		False	Whether every result can be fixed in one go, rather than one at a time.
category	text			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
fix	true or false		False	Whether a result offers to fix the thing it found.
fix_input_control	text, textarea		text	What the person fixing a result types into: a single line, or a larger box.
icon	text		bolt	The 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		1	How serious a result is: 0 for low, 1 for medium, 2 for high.
language	python		python	The language the check is written in.
rave_linter	true or false		True	Whether the diagnostic runs against Rave drafts.
settings_help	text			Help text shown with the diagnostic's own settings.
tags	text			The kinds of object this diagnostic reports on, separated by commas. Used to group results.
vault_linter	true or false		False	Whether the diagnostic runs against Vault drafts.
version	text			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_location	location		where 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
name	text	yes		What the template is called where people choose one.	at least 1 character; at most 100 characters
template	text	yes		The template itself: the markup that says what the produced document contains.
active	true or false		True	Whether the template is offered. An inactive one is kept but not shown.
description	text			What the template produces, to help somebody choosing between templates.
is_locked	true or false		False	Whether the template is protected from being edited.
object_type	text			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
settings	blocks 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 Home	Where in the application the template is offered.
template_type	Word, PDF, Excel 2003/2004 SpreadsheetML, Excel 2003/2004 SpreadsheetML with conversion to XLSX, Text, AI Summary		Word	What kind of document the template produces.
text_extension	text			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_name	text	yes		What the person producing a document sees this setting called.	at least 1 character; at most 100 characters
name	text	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, draft	yes		What kind of answer the setting takes.
default_value	text			The answer the setting starts with.	at most 255 characters
description	text			Help text shown with the setting.	at most 2000 characters
display_order	whole number		1	Where this setting sits among the template's others. Lower numbers come first.
multiple	true or false		False	Whether more than one draft may be chosen. Only for setting_type draft.
required	true or false		False	Whether 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_choices	list 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_location	location		where 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
name	text	yes		What the property is called. This is the label people see against it.	at least 1 character; at most 100 characters
active	true or false		True	Whether the property is in use. An inactive one keeps what it holds but is not offered for editing.
can_be_copied	true or false		True	Whether the property's value comes along when a record is copied.
description	text			Help text shown with the property, to say what somebody should put in it.
display_order	whole number		1	Where 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_context	true or false		False	Whether the property's value is given to agents working on the record.
llm_instruction	text			What to tell an agent about this property, when it is given to one.
numeric_decimal_places	whole number			How many decimal places a number is kept to. Only for value_type numeric.	0 or more
numeric_max_value	number			The largest number allowed. Only for value_type numeric, and it cannot be below numeric_min_value.
numeric_min_value	number			The smallest number allowed. Only for value_type numeric.
reference_type	text			The object a reference points at, by name. Required when value_type is reference, and refused otherwise.	at most 100 characters
reserved_for_actions	true or false		False	Whether the property is set only by actions. People cannot edit one that is.
set_separator	text		|	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_values	list 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_lists	true or false		False	Whether the property appears as a column when records are listed.
text_max_length	whole number			The longest a text value may be. Only for value_type text.	1 or more
text_validation_regex	text			A regular expression a text value must match. Only for value_type text.	at most 500 characters
value_choices	list 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, email, uri, color, numeric, date, datetime, set, user		text	What 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_location	location		where 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_name	text	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
name	text	yes		What one of these objects is called.	at least 1 character; at most 100 characters
plural_name	text	yes		What several of them are called. Used wherever a list of them is shown.	at least 1 character; at most 100 characters
description	text			What this kind of object is for.
display_order	whole number		1	Where this object sits among the others in lists and menus. Lower numbers come first.
has_ordinal	true or false		False	Whether these objects are numbered, so they keep an order of their own.
icon	text			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_separator	text		|	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_instruction	text			What to tell an agent about this kind of object, when it works on one.
parent	text			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_location	location		where 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_object	text	yes		The object whose identifier you are adding to, by name.	at least 1 character; at most 100 characters
property	text	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_location	location		where 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
name	text	yes		What the property is called. This is the label people see against it.	at least 1 character; at most 100 characters
active	true or false		True	Whether the property is in use. An inactive one keeps what it holds but is not offered for editing.
can_be_copied	true or false		True	Whether the property's value comes along when a record is copied.
description	text			Help text shown with the property, to say what somebody should put in it.
display_order	whole number		1	Where 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_context	true or false		False	Whether the property's value is given to agents working on the record.
llm_instruction	text			What to tell an agent about this property, when it is given to one.
numeric_decimal_places	whole number			How many decimal places a number is kept to. Only for value_type numeric.	0 or more
numeric_max_value	number			The largest number allowed. Only for value_type numeric, and it cannot be below numeric_min_value.
numeric_min_value	number			The smallest number allowed. Only for value_type numeric.
reserved_for_actions	true or false		False	Whether the property is set only by actions. People cannot edit one that is.
set_separator	text		|	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_values	list 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_lists	true or false		False	Whether the property appears as a column when records are listed.
text_max_length	whole number			The longest a text value may be. Only for value_type text.	1 or more
text_validation_regex	text			A regular expression a text value must match. Only for value_type text.	at most 500 characters
value_choices	list 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, email, uri, color, numeric, date, datetime, set, user		text	What 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_location	location		where 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
name	text	yes		What the property is called. This is the label people see against it.	at least 1 character; at most 100 characters
active	true or false		True	Whether the property is in use. An inactive one keeps what it holds but is not offered for editing.
description	text			Help text shown with the property, to say what somebody should put in it.
display_order	whole number		1	Where 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_context	true or false		False	Whether the property's value is given to agents working on the record.
llm_instruction	text			What to tell an agent about this property, when it is given to one.
numeric_decimal_places	whole number			How many decimal places a number is kept to. Only for value_type numeric.	0 or more
numeric_max_value	number			The largest number allowed. Only for value_type numeric, and it cannot be below numeric_min_value.
numeric_min_value	number			The smallest number allowed. Only for value_type numeric.
reserved_for_actions	true or false		False	Whether the property is set only by actions. People cannot edit one that is.
set_separator	text		|	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_values	list 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_lists	true or false		False	Whether the property appears as a column when records are listed.
text_max_length	whole number			The longest a text value may be. Only for value_type text.	1 or more
text_validation_regex	text			A regular expression a text value must match. Only for value_type text.	at most 500 characters
value_choices	list 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, email, uri, color, numeric, date, datetime, set, user		text	What 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_location	location		where 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_object	text	yes		The object to show or hide, by name.	at least 1 character; at most 100 characters
visible	true 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_location	location		where 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
data	text	yes		The image file, a PNG, JPEG or GIF, as base64. Line breaks in it are ignored.
token	UUID	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_location	location		where 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
content	text	yes		The Markdown to add to the end of the page, after a blank line.	at least 1 character
title	text	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_location	location		where 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
name	text	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_location	location		where 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_text	text	yes		What replaces it. Empty to delete the text.
old_text	text	yes		The text to replace, exactly as the page holds it: case, spaces and line breaks all count.	at least 1 character
title	text	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_all	true or false		False	Replace 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_location	location		where 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
content	text	yes		The whole of the page, in the wiki's Markdown. It replaces what the page holds.
title	text	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.

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.

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_location	location		where 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
identifier	text	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_location	location	yes		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.
type	text	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_identifier	text			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 type somebody defined there, and Form, Folder, Matrix, Custom Function and Test Case, can have records created this way. The other built-in types - Field, Edit Check 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.

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 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 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_location	location		where 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
attributes	text, 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 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, and a Custom Function a name and its source code. A Test Case takes Name, Script, IsTemplate and Priority, and has to be given a name and a script. 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.
type	text	yes		The kind of record to create, by the name the object type is given on this URL. Case does not matter.	at least 1 character; at most 100 characters
parent_identifier	text			For an object type that sits inside another, the identifier of the record this one belongs in. 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

ImportRelatedObjects

Import every applicable matrix, edit check and derivation from the Standard Library, being those whose prerequisites this draft already satisfies.

Argument	Accepts	Required	Default	What it is	Limits
draft_location	location		where 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

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_location	location		where 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_location	location	yes		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_location	location		where 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_oid	text	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_oid	text	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_oid	text	yes		The OID of the matrix. Case does not matter.	at least 1 character; at most 2000 characters
on	true or false	yes		True to put the form in that folder of the matrix, false to take it out.