Creating Import Queue templates for Activity Instance Import
This is still in draft form! If you’ve come across this and would find this guidance helpful, send Seth a message and let him know to move it to the top of the documentation queue. Thanks!
Overview
The https://heuristicsolutions.atlassian.net/wiki/spaces/DOCS/pages/1462567034 feature allows users to import a file containing ActivityInstance data into LearningBuilder.
There are many different business scenarios that can be implemented with this feature, and the specific outcome of processing a given row depends on the columns in the file and the data in that row.
To ensure that users upload the correct data, configurators will typically construct a template file containing the columns that should be uploaded.
This document provides guidance on creating those template files.
Getting started: which operations do you want to perform?
TODO
Choose the “identifier columns” your file will use
TODO
Identify the Workflow Action you want to perform
The Import Queue is a Workflow-centric feature. Every row of an uploaded file is mapped to a specific Workflow Action on a specific Data Import Step that is triggered by the import.
Before you can create your template, identify the Workflow Action that you want to be performed against each uploaded row.
Once you know the Action, you need to decide how to tell the system which Action you selected.
There are two ways for this mapping to occur:
Your file can explicitly specify a
:WorkflowActionNameor:WorkflowActionIdcolumn, ORThe system can try to figure it out dynamically
It is highly recommended that you include the :WorkflowActionName column in your file!
The “figure it out dynamically” approach only works when the Complete Activity Workflow for :ActivityId has a single Data Import Step, with a single Action on that Step.
If you omit the :WorkflowActionName column, you run the risk that future changes to the Workflow configuration (e.g. adding a second Data Import Step) will break your file. No diagnostic checks will alert you that this has happened; you won't know until someone tries to use your template and it doesn't work.
If every row in the file should map to the same Action, then you can include a “sample row” that contains that Action’s name in the :WorkflowActionName column. This is a helpful way to show users what they should be uploading.
If different rows in the file could map to different Actions, then you should provide instructions (either in the template, or in client-specific training materials) on how to specify the Action name in the file. (If that is too complex, then consider splitting your process into separate Templates, one for each possible Action)
Add columns for each Workflow Attribute on the Import Step
Once the system has identified the ActivityInstance to update (or created a new one), it will perform the relevant Workflow Action.
This includes:
Updating the Workflow Attributes to match the data columns in the file;
Executing the target Action (and any Behaviors it includes)
Your file should include columns for each of the editable Attributes on your target Step. If any of those Attributes are marked as required, but the uploaded file does not contain a value, that row will be rejected.
Save your template in .csv format
Now that you have a complete file template, save it as .csv format.
Your users are welcome to open the file in Excel if they need to enter data by hand, they just need to save the file as .csv when finished.
Attach it to the “File Type” configuration
Go to Admin → Data Import → File Types and attach your .csv file to the relevant File Type. It will then become available to end users.