What are field aliases?
Field aliases are labels assigned to unique pieces of information in the chaotic world of PDFs. Within the Anvil ecosystem, field aliases are used to easily reference data and simplify mapping across systems.
We purposely separate field names from the underlying field alias for a few reasons; one being the varied nature of PDF field names as they exist in the world today. Anyone who has ever worked with fillable PDFs can attest that field names are often not descriptive and inconsistent across PDFs. Field aliases are a consistent way to refer to the same piece of data across multiple PDFs without having to relabel every field name.
Most importantly, we want to decouple the PDF from the data as much as possible. For a user, PDF forms are often confusing and duplicative, so the experience of completing a form is drastically improved by abstracting the data collection away from the PDF.
A personalized webform provides an opportunity to ask for information in a way that’s more intuitive to a person, but comes with its own challenges for normalizing data. When completing payroll documents, you may want to ask for an employee’s name in their primary language (nombre, nom, name, etc.). Further still, you may want to ask the employee for “your name” to make the experience feel more personal. To know whether that name is the name of the employee or the company hiring them, “your name” may not be specific enough out of context. At the end of the day, you’re looking for the same unique piece of information and to make it machine-readable, you need a consistent, unambiguous way of referencing it.
Within Anvil, there are a couple of ways data is referenced via field aliases:
-
In document templates, each PDF field can have a field alias in addition to a field name. When a document template is filled via the PDF Fill or Etch API, the field alias referenced in the payload will send data to the fields on the PDF or PDFs with the same field alias. In this way, Anvil can automatically route one piece of data to multiple destinations.
-
In Workflows (including those created from document templates), the field alias exists at the webform field level. Webform fields can be mapped to fill one or more fields on a PDF or set of PDFs. They can also be used to capture data that isn’t output on a PDF or to drive the logic of the Workflow itself. For Workflow API users, field aliases simplify the requests to control the Workflow and the data payload created from a completed Workflow.
Why are they so special?
More than any other Anvil feature, field aliases unlock effective collaboration between developers and non-technical business process experts. Anvil’s tools for templatizing documents and building Workflows are no-code for a reason: we want to empower the experts most familiar with a given business process to codify it in a way that meets industry standards, operational norms, or customer expectations. With our APIs, we want to enable developers to build API-driven applications that can scale that process beyond human efficiency. The field alias is the bridge that allows non-technical and technical users to leverage their respective areas of expertise when building new applications together.
Best practices for using field aliases
As a general rule, it is most efficient for non-technical business users to use Anvil’s no-code UI to create document templates and Workflows to be consumed over API while developers focus on building and testing the integration. Field aliases, the link between the two, need to be defined and communicated clearly so that they can be implemented by both sides.
If your team is planning on using field aliases, it’s best practice to follow these steps:
- Define your field alias “library”.
- Add that library to your document template as the allowed field aliases.
- Update your document template to use the list of field aliases from the library.
- As needed, create Workflows from those document templates.
1. Define your field alias library
Anvil field aliases must be camelCase and cannot contain any spaces, numbers, or special characters. You’ll want to come up with a naming convention that is both consistent and specific enough to account for every unique piece of data you will need to collect.
You should start with a general review of your documents to understand the data overlap and how it’s organized. Once you have a sense for what data is shared and what level of specificity you’ll need to create unique field aliases, you can propose and test out a schema.
For example, if you are an HR tech company completing onboarding documents for new hires, the field alias “name” will not be specific enough. In some cases, a name field refers to the employee name and in others it refers to the employer. Before you go too far down the road of creating your field alias library, you’ll want to know how you want to construct it.
Continuing with our HR example, your library may include “employeeName”, “employeeAddress”, “employerName”, “employerAddress”.
2. Add your library to your document template
At this time, the list of aliases must be updated via the API for each document template. You can use the updateCast mutation:
mutation updateCast($eid: String!, $allowedAliasIds: [String]) {
updateCast(eid: $eid, allowedAliasIds: $allowedAliasIds) {
eid
allowedAliasIds
}
}Then update the PDF template
updateCast({
eid: 'yourPDFTemplateEid',
allowedAliasIds: [
'employeeName',
'employeeAddress',
'employerName',
'employerAddress',
],
})3. Update your document templates
Once your document template has the list of field aliases, only those aliases will be available for selection.
4. As needed, create Workflows from those document templates.
If you intend to fill your PDF(s) via an Anvil Workflow, you can create the Workflow from the document template(s). Anvil will automatically generate webform fields connected to the corresponding PDF fields and move the field alias to the webform field. At this stage, you should remove any duplicate webform fields and connect the remaining webform field to all its destinations on the PDF(s). You can also customize your webform with page breaks, logic, unconnected fields, and explanation text.
When a single Workflow requires both pre-existing, internal data and new, external data to complete a set of documents, field aliases are the simplest way to map the internal data to a Workflow with multiple webforms or a single webform with hidden fields. You’ll probably also want to use field aliases to map any updated or new data gathered by the Workflow back to your database.
Since this is a more complex use case, let’s return to our previous hiring documents example. In order to complete a set of onboarding documents that require both existing employer information ( name, address, ein) and new employee information (name, ssn, address), you can set up a single Workflow with two webforms, an internal “employer” webform and an external “employee” webform. The “employer” webform can be completed over API with data you already have about the employer, mapped to the webform via field aliases.
Once the internal webform is completed, you’ll share a unique link with the employee to complete their webform. This can be done manually via the submission dashboard or automatically via webhook trigger. The employee can then complete the “employee” webform of the same submission to provide their information before signing the documents.
Once this or any other Workflow with field aliases is completed, the data is stored in the submission and referenced by its field alias. If you are using webhooks to get submission data back from Anvil, the payload will use the pre-assigned field aliases. In other words, it is ready to be ingested in a programmatic way!
Get in touch
To learn more about how field aliases can help your company simplify data collection, please reach out to sales@useanvil.com for more information.