Onit allows end-users to upload files (e.g., documents, spreadsheets) and emails directly into Records. While building a workflow, you can 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
All Actions covered in this tutorial can access emails stored within a Record. If you’re unaware, 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 files that live in a Record (excluding emails sent to the Record’s email address). For example, uploading a file into a Record’s Attachment or DocumentFolder Field 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 a 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 another (different) Record, such as 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 from which you want to copy the file. 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 often moves files from one Field to another on the same Record. It can also retrieve an email or file from 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 containing a comma-separated list of document IDs 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 for this configuration property, 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. Only the first one will be saved if you attempt to copy several files into an Attachment Field. 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 from 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 these conditions work, let’s say you only want the .docx attachment from a received email in 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 attempt to store email attachments in an Attachment Field, this Field can only contain a single File, meaning 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 triggered via an Email Received Business Rule or an Action Button.
- Attachment Fields can only hold one file. If several attachments are copied, 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 listed under the 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 copy attachments from one App to another 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 and 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 to the parent App. The two Apps are related through the attachments Field. We create an Update Transaction Action on the parent App 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 %}