Onit allows end-users to upload files (e.g., documents, spreadsheets) and emails directly into Records. While building a workflow, you may want to programmatically copy files/emails from their original Record into a different/separate Record, or from one area of a Record into a different area of the same record.
For example, let’s say that a Record is created in a Legal Service Request app. At the end of this Record’s life, a user clicks a Button on the Record to create a new related Record in a different App named Matter. The new Matter Record should inherit various data from the Legal Service Request Record, including its files/emails.
Onit provides various Actions to solve business problems like these. In this tutorial we’ll cover each one.
The Actions covered below work best between Records that are related via HasMany – BelongsTo Fields. Some of the Actions covered in this tutorial don’t cover ManyToMany relationships.
Files, Documents and Emails. Oh my!
All of the Actions covered in this tutorial have the ability to access emails stored within a Record. In case you’re not already aware, all Onit Records have a dedicated email address. If an email is sent to this address, the email (and all of its attachments) will be stored within the Record’s Activity Panel (as seen in the screenshot below).
To programmatically interact with emails and files that live within a Record, you must be familiar with the two objects listed below. Every Record contains these two objects:
- A
documentsobject: Contains all of the files that live in a Record (excluding emails sent to the Record’s email address). For example, if you upload a file into a Record’s Attachment or DocumentFolder Field, it will be stored in thedocumentsobject. - An
emailsobject: Contains emails sent to the Record’s email address. Interestingly, any attachments contained within an email will be stored within thedocumentsobject.
Since the objects above are accessible via Liquid, you can loop over each object and retrieve information/properties about a document/file. Building these types of loops are required to use the Actions covered in this tutorial, and examples will be provided below.
From a terminology standpoint, this tutorial will use the term “file” to refer to any file stored within a Record that is not an email. A “file” may be Word document, but it also may be an Excel spreadsheet, an audio recording, etc. Using this terminology, the items within the documents object are “files.”
Action: "Copy Document Property to Related Transaction"
This Action copies a single file from one Record to one or more other (different) Records. For example, from one parent Record to one or many child Records. The file must live in an Attachment Field on the source Record.
Configuration properties:
- Source Attachment Property: Choose the Attachment Field that you want to copy the file from. The document can only be transferred from an Attachment Field, a DocumentFolder Field will not work.
- Related Atom Field: A dropdown list of the source App's relation Fields. This determines which App the file will be copied to. This Field can only be a HasMany Field, in other words you can copy documents from a parent to a child Record but not from a child to a parent Record.
- Related Atom Attachment Property: The name of the Attachment Field (in the target App) that you want to copy the file into. The Field name does not have to be prepended with p_.
Action: Copy Documents from Document IDs
This Action is often used to move files from one Field into another Field on the same Record. In addition, it can be used to retrieve an email or file out of a Record’s Activity Panel and move it into the same Record’s Attachment Field.
Configuration properties:
- Document ID Field: A Text or Textarea Field that contains a comma separated list of document IDs that you want to copy.
- Liquid Document ID: Same as above, except the source of the IDs is a Liquid expression that outputs a comma separated list of IDs. If you provide a value into this configuration property then any value entered into the Document ID Field will be ignored.
You’re probably wondering: How do I get the IDs? You’ll want to build a Liquid for loop that iterates over the Record’s documents object and captures each file’s id value. As your loop iterates it should populate a new variable (that you must create) that ultimately contains a comma separated list of IDs (if your loop only finds one ID, no comma should be inserted). Below is an example of a for loop that tackles this problem.
{% capture var1 %}
{% for doc in documents %}
{{ doc.id }}
{% unless forloop.last %}
,
{% endunless %}
{% endfor %}
{% endcapture %}
{{ var1 }}- Attach To: A dropdown list of all Attachment Fields in the current App. Choose the appropriate Attachment Field for the file(s) to be copied into.
Attachment Fields can only hold one file. If you attempt to copy several files into an Attachment Field then only the first one will be saved. Alternatively you can copy multiple files into a DocumentFolder Field.
Action: Copy Received Mail Attachment
As mentioned above, emails – with attachments – can be sent to Onit Records. The Copy Received Mail Attachment Action allows you to copy email attachments out of a Record’s Activity Panel into an Attachment Field or DocumentFolder Field on the same Record.
Important: The Copy Received Mail Attachment Action should only be used inside of an Email Received Business Rule.
Configuration properties:
- Condition: An optional condition to determine if the received attachment should be copied to a Record. When the Action is fired from an Email Received Business Rule, this Condition has a context of the individual attachments associated with the received email. As an example of how this conditions work, let’s say that you want to only the .docx attachment off of a received email into an Attachment Field. To do so, use the following Liquid:
{% if name contains "docx" %} true {% endif %}
Note: This Liquid does not need a loop to copy multiple attachments because the Copy Received Mail Attachment Action automatically loops over each individual attachment on the email. That said, if you are attempting to store email attachments into an Attachment Field, this Field can only contain a single File, which means only one will ultimately be copied. On the other hand, if you are working with a DocumentFolder Field, you can use the Action to copy multiple Files into the target Field.
- Attach To: A dropdown list of all attachment Fields in the App. Choose the appropriate Attachment or DocumentFolder Field for the document(s) to be copied into.
Limitations:
- This Action must be trigger via an Email Received Business Rule or an Action Button.
- Attachment Fields can only hold one file. If several attachments are copied, then only the first one will be saved, and the rest discarded. For multiple attachments use a DocumentFolder field.
- The email's sender must be an existing user in the Onit environment, that is listed under Corporation Users node in the environment’s /admin page under a Status of Active.
Action: Update Transaction Action
The following configuration only works on attachment Fields.
The Update Transaction Action can be used to copy attachments from one App to another App related by a HasManyBelongsTo Field (i.e., a parent-child relationship). This configuration works by looping over an Attachment Field to access the document ID then updating the parent Record with that document ID.
For example, the child App, New Document, contains a signed document in the attachment Field child_attachment. We want to transfer this the parent App. The two Apps are related through the attachments Field. On the parent App we create an Update Transaction Action to loop over the child's attachment Field.
{% for att in attachments %}{% for doc in newDocument %}{{ doc.childAttachment }}{% endfor %}{% endfor %}
{% for h in hasMany / belongsTo %}{% for c in children %}{{ c.attachment Field }}{% endfor %}{% endfor %}