<a id="command-reference"></a>
<a id="script-commands"></a>
# 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](../import_scripts.html.md#import-script-paths).

<a id="what-each-command-does"></a>
## 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](#script-command-addwikiimage) | Add an image for a project's wiki pages to show. |
> | [AppendToWikiPage](#script-command-appendtowikipage) | Add text to the end of a project's wiki page. |
> | [CopyDraftObject](#script-command-copydraftobject) | Copy one record - a form, an edit check, a record of a type you defined - from another draft into this one. |
> | [CreateCustomDiagnostic](#script-command-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](#script-command-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](#script-command-createdraft) | Create an empty draft in a project, as the New Draft page does. |
> | [CreateDraftObject](#script-command-createdraftobject) | Create one record of an object type, with the values it holds. |
> | [CreateDraftPropertyDefinition](#script-command-createdraftpropertydefinition) | Add a property that every draft in this URL can hold. |
> | [CreateIcon](#script-command-createicon) | Add an icon your Organization can use wherever an icon is chosen. |
> | [CreateObjectDefinition](#script-command-createobjectdefinition) | Add a kind of object of your own, such as a Visit or a Country, for this URL to hold records of. |
> | [CreateObjectIdentifier](#script-command-createobjectidentifier) | Make one of an object's existing properties part of its unique identifier. |
> | [CreateProjectPropertyDefinition](#script-command-createprojectpropertydefinition) | Add a property that every project in this URL can hold. |
> | [CreatePropertyDefinition](#script-command-createpropertydefinition) | Add a property to one of this URL's objects, so its records can hold that value. |
> | [CreateTicketPropertyDefinition](#script-command-createticketpropertydefinition) | Add a property that every ticket in this URL can hold. |
> | [EditWikiPage](#script-command-editwikipage) | Replace text in a project's wiki page. |
> | [ImportRelatedObjects](#script-command-importrelatedobjects) | Import every applicable matrix, edit check and derivation from the Standard Library, being those whose prerequisites this draft already satisfies. |
> | [LinkDraftToLibrary](#script-command-linkdrafttolibrary) | Point a draft at the Standard Library it is built from. |
> | [SetMatrixFolderForm](#script-command-setmatrixfolderform) | Put a form in a folder of a matrix, or take it out. |
> | [SetObjectDefinitionVisible](#script-command-setobjectdefinitionvisible) | Show or hide one of this URL's objects, without changing anything it holds. |
> | [SetWikiPage](#script-command-setwikipage) | Write a project's wiki page, creating it if it does not exist. |
> | [UpdateDraftObject](#script-command-updatedraftobject) | Change the values of one record a draft already holds. |
> | [UpdateProject](#script-command-updateproject) | Change a project's settings and custom properties, as the Edit Project page does. |

<a id="commands-that-act-on-your-organization"></a>
## Commands that act on your Organization

What these create belongs to your whole Organization, so they are available wherever a run is pointed.

<a id="createicon"></a>
<a id="script-command-createicon"></a>
### 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](../import_scripts.html.md#import-script-paths) |  | 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. |  |

<a id="commands-that-act-on-a-url"></a>
## 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.

<a id="createpropertydefinition"></a>
<a id="script-command-createpropertydefinition"></a>
### 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](../import_scripts.html.md#import-script-paths) |  | 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. |  |

<a id="createcustomdiagnostic"></a>
<a id="script-command-createcustomdiagnostic"></a>
### 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](../import_scripts.html.md#import-script-paths) |  | 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 |

<a id="createdocumenttemplate"></a>
<a id="script-command-createdocumenttemplate"></a>
### 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](../import_scripts.html.md#import-script-paths) |  | 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. |  |

<a id="createdraftpropertydefinition"></a>
<a id="script-command-createdraftpropertydefinition"></a>
### 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](../import_scripts.html.md#import-script-paths) |  | 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. |  |

<a id="createobjectdefinition"></a>
<a id="script-command-createobjectdefinition"></a>
### 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](../import_scripts.html.md#import-script-paths) |  | 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 |

<a id="createobjectidentifier"></a>
<a id="script-command-createobjectidentifier"></a>
### 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](../import_scripts.html.md#import-script-paths) |  | 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 |

<a id="createprojectpropertydefinition"></a>
<a id="script-command-createprojectpropertydefinition"></a>
### 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](../import_scripts.html.md#import-script-paths) |  | 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. |  |

<a id="createticketpropertydefinition"></a>
<a id="script-command-createticketpropertydefinition"></a>
### 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](../import_scripts.html.md#import-script-paths) |  | 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. |  |

<a id="setobjectdefinitionvisible"></a>
<a id="script-command-setobjectdefinitionvisible"></a>
### 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](../import_scripts.html.md#import-script-paths) |  | 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. |  |

<a id="commands-that-act-on-a-project"></a>
## Commands that act on a project

<a id="addwikiimage"></a>
<a id="script-command-addwikiimage"></a>
### AddWikiImage

Add an image for a project's wiki pages to show.

Pages show the image by its token, written as ![caption](/image/<token>), 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](../import_scripts.html.md#import-script-paths) |  | 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 ![Figure 1](/image/<token>). |  |

<a id="appendtowikipage"></a>
<a id="script-command-appendtowikipage"></a>
### 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](../import_scripts.html.md#import-script-paths) |  | 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. |  |

<a id="createdraft"></a>
<a id="script-command-createdraft"></a>
### 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](../import_scripts.html.md#import-script-paths) |  | 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 |

<a id="editwikipage"></a>
<a id="script-command-editwikipage"></a>
### 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](../import_scripts.html.md#import-script-paths) |  | 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. |  |

<a id="setwikipage"></a>
<a id="script-command-setwikipage"></a>
### 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](../import_scripts.html.md#import-script-paths) |  | 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. |  |

<a id="updateproject"></a>
<a id="script-command-updateproject"></a>
### 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_location` | [location](../import_scripts.html.md#import-script-paths) |  | 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 |
> | `attributes` | text, 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 |

<a id="commands-that-act-on-a-draft"></a>
## 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.

<a id="copydraftobject"></a>
<a id="script-command-copydraftobject"></a>
### 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_location` | [location](../import_scripts.html.md#import-script-paths) |  | 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](../import_scripts.html.md#import-script-paths) | 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 |

<a id="createdraftobject"></a>
<a id="script-command-createdraftobject"></a>
### 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_location` | [location](../import_scripts.html.md#import-script-paths) |  | 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 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. |  |
> | `type` | text | 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_identifier` | text |  |  | 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 |

<a id="importrelatedobjects"></a>
<a id="script-command-importrelatedobjects"></a>
### 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](../import_scripts.html.md#import-script-paths) |  | 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 |

<a id="linkdrafttolibrary"></a>
<a id="script-command-linkdrafttolibrary"></a>
### 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](../import_scripts.html.md#import-script-paths) |  | 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](../import_scripts.html.md#import-script-paths) | 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. |  |

<a id="setmatrixfolderform"></a>
<a id="script-command-setmatrixfolderform"></a>
### 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](../import_scripts.html.md#import-script-paths) |  | 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. |  |

<a id="updatedraftobject"></a>
<a id="script-command-updatedraftobject"></a>
### 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_location` | [location](../import_scripts.html.md#import-script-paths) |  | 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 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 |
> | `identifier` | text | 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 |
> | `type` | text | 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_identifier` | text |  |  | 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 |
