# 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). ## 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. | ## 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](../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. | | ## 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](../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. | | ### 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 | ### 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. | | ### 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. | | ### 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 | ### 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 | ### 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. | | ### 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. | | ### 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. | | ## 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](../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/, 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](../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. | | ### 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 | ### 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. | | ### 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. | | ## 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](../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 | ### 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](../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 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](../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 | ### 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. | | ### 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. | |