Import Scripts

An Import Script reads a file you upload and creates objects in the TrialGrid system by reading the contents of the file and executing commands to modify data in the system.

You write an Import Script once for your Organization. Other people in your Organization then run it whenever they have a file to load.

Note

Import Scripts are being built in stages. At present you can register a script, write its code, and test it against a file to see what it would do. Running a script for real, so that it creates and changes objects, is not available yet.

Registering a script

To see the Import Scripts for your Organization:

Go to your Organization home page.
Click the "Import Scripts" card.

You will see the scripts already registered, with the Scope and File Type of each and whether each one is Active.

Click "Add Import Script" to register a new one. You will be asked for:

Name: What the script is called. Names must be different from each other within your Organization.
Description: What the script does, so that someone choosing a script knows which one they want.
Scope: The level the script runs at. See Choosing a Scope below.
File Type: The kind of file the script expects: Excel, JSON or YAML.
Active: An Inactive script is kept but is not offered to be run. New scripts start as Inactive so you can finish writing one before anyone can use it.

Choosing a Scope

The Scope sets the level the script runs at. It decides what the script is told about its surroundings when it runs.

Scope	The script is told about
Organization	The Organization
URL	The Organization and the URL
Project	The Organization, the URL and the Project
Draft	The Organization, the URL, the Project and the Draft

Pick the level the file belongs to. A file listing forms to copy into a new Draft belongs to a Project, so that script has Project scope. A file that creates a set of Projects belongs to a URL, so that script has URL scope.

Writing the code

The Code tab holds the body of the script. The editor shows line numbers and colors the code as you type.

When you save, TrialGrid checks that the code is valid. If it is not, the page tells you what is wrong and which line it is on, and your work is kept on screen so you can correct it. Nothing is run at this point. The check only confirms that the code can be read.

You can save a script with no code in it. This lets you register a script and come back to write it.

Settings

A script often needs a value that it cannot read from the input file itself. For example, a script that copies forms from a library has to be told which library. That is a setting.

You declare the settings a script needs on the Settings tab. The person running the script is then asked for those values each time. You are asked for them when you test a script, so you can try a script with different values.

Each setting has:

Name

The name the script uses to read the setting. Keep it short and do not change it once the code uses it.

Display Name

The label shown to the person running the script.

Description

Help text shown under the field.

Type

What kind of value it is. See the table below.

Options

For a Choice setting, the values to choose from, separated by commas.

An option cannot contain a comma. If you type Yes, please,No you get three options, Yes, please and No, not two. Space around a comma is removed, so Yes, No and Yes,No give the same two options.

Default Value

The value the run form starts with. The person running can change it or clear it. Clearing it means the script gets no value for that setting, not the default.

Required

Whether the script can be run without a value.

Setting types

Type	What the person running the script gives
Text	Any text
Boolean	True or False
Choice	One of the options you list
Integer	A whole number
Draft	A Draft to copy from
Project	A Project
URL	A URL

Draft, Project and URL settings hold an object rather than a typed value. These cannot have a default value, because an object belongs to one Organization and not everyone may use it. Leave the Default Value empty for them, and the person running the script chooses the object each time.

The order of the rows is the order the settings are shown in. Drag a row to move it.

Checks on the settings you enter

Two settings on the same script cannot share a Name or a Display Name. A Choice setting needs at least one option, and its default has to be one of them. A Boolean default has to be True or False, and an Integer default has to be a whole number. If any row has a problem the page tells you which row and does not save, and your rows are kept on screen.

TrialGrid also compares the settings you declared against the settings your code reads. If your code reads a setting you have not declared, or you declare one the code does not appear to read, you are told after the save. These are notes, not errors. The script is saved either way, because there are good reasons for the two to differ: your code might read a setting only in certain cases, or work out the name while it runs.

Testing a script

The Code tab has a Test panel beside the editor. Use it to run your script against a real file and see what it would do, without anything being created or changed.

Choose the target, choose a file, fill in any settings your script declares, and select Run Test. TrialGrid runs the saved script, so save your changes first. The panel tells you if you have unsaved work.

Choosing the target

The target is the object your script works in. Which kind it is comes from the script's scope: a Draft scope script is pointed at a Draft, a Project scope script at a Project, and a URL scope script at a URL. An Organization scope script has no target to choose. It runs against your Organization.

Start typing in the target box to search. The list holds only the objects you are allowed to see, inside the Organization that owns the script. It is searched as you type because an Organization can hold many thousands of Drafts.

Drafts and Projects are listed under the URL and Project they belong to. A Project that holds Standard libraries is marked with a library icon, so you can tell a library Draft from a study Draft before you choose one.

Your choice is checked again when the run starts. If your permission has changed since you chose it, the run stops and tells you to choose another.

Reading the target

Your script reads the target as importer.context:

draft = importer.context.draft
importer.log(draft.DraftName)

for form in draft.als_forms_set.all():
    importer.log(form.OID)

The target also tells your script about the levels above it. A Draft knows its Project, and that Project knows its URL, so importer.context.project and importer.context.url work without you choosing them.

The names you use are the same ones a Document Template uses. See the Object Model Reference for what each kind of object gives you. Reading something the reference does not list stops the run and names the line, so a mistyped attribute is reported rather than silently empty.

Custom properties work the same way as in a Document Template. Every property defined for the URL is there, including ones nobody has filled in:

for name, prop in importer.context.draft.properties.items():
    importer.log(f"{name} = {prop.value}")

The properties you get are the ones defined for the URL your run is pointed at. If your script follows a link to an object in a different URL, such as a Standards Draft reached through get_compliance_chain(), you will be shown the property names of the URL your run is pointed at, none of them set. An object chosen in a Draft, Project or URL setting carries its own URL, so its properties are read correctly.

Settings that name an object

A Draft, Project or URL setting is chosen the same way as the target, from its own searchable box in the Test panel, with the same library icon on Projects that hold Standard libraries. A Draft box offers only Drafts that allow importing.

What you choose stays chosen when you save the script, so you can edit and run without picking your test values again each time.

Your script reads the choice as it reads anything else:

library = importer.settings["source_library"]

for row in importer.file.sheet("Forms").rows():
    form_oid = row["Form OID"]
    importer.log(f"looking for {form_oid} in {library.DraftName}")

If you leave one empty, reading it stops the run and says nothing was chosen. If the object you chose is one you can no longer use, the run stops before it starts and asks you to choose again.

What you get back

The log shows every line your script wrote with importer.log, importer.warn or importer.error, in the order it wrote them.

Below the log is the list of commands your script asked for. These are checked, so a command with values it will not accept is reported here rather than when the script is run for real. The commands are listed only. Nothing is created and nothing is changed.

If your script stops with a problem, the log says which line of your code failed and why. Anything the script did before that point is still shown, so a run that logged forty rows and then failed on the forty-first tells you about the forty.

Nothing is kept

A test run leaves no record. The file you chose is read and then removed, and the Runs tab stays empty.

What a test run cannot do yet

A test run cannot carry out the commands your script asks for. They are listed instead, so you can see what would happen without anything being created or changed.

Two names in the Object Model Reference are not available to a script yet, because a Document Template builds them while it renders rather than reading them from the object. They are activities and ticketobjectrelation_set. Reading either one stops the run and says so.

Limits

A test run has limits, so one script cannot tie up the system:

it can run for up to 3 minutes, and reading a large sheet counts towards that
it can write up to 500 log lines, and any beyond that are not kept
it can build up to 1000 commands
the file can be up to 20 MB, and a run reads up to a million cells from it

Permission

To add, change or delete an Import Script you need the "Can manage Import Scripts" permission. Permissions come from your Organization Role, so ask someone who can administer permissions to put you on a role that has it. They choose the role on the organization team page.

Being able to administer permissions does not give you this permission by itself. Someone who administers permissions and also wants to manage Import Scripts puts themselves on a role that has both.

An Import Script is code that other people in your Organization will run. Give this permission only to people you trust to write it.

Anyone in your Organization can see the Import Scripts card and open a script to read it, including its code. The fields are shown but cannot be changed, there is no Save button, and Delete is not offered. Only the permission decides who can change a script, not who can see one.