Archer is built to be configured without code. Calculated fields, advanced workflow, data-driven events, and dashboards cover the large majority of what most organizations need, and they're the right first stop for any requirement. They're supported, they upgrade cleanly, and they don't require a developer to maintain. Before building a custom object, the question worth asking is always: can a native feature do this? Often the answer is yes, and the native path is the better one.

Custom objects exist for the genuine gaps, such as the cases where you need behavior the platform doesn't offer natively. For example, users could create a button that performs a specific action on click, or build an integration that pulls information from another system into the record. These specific situations extend Archer beyond its configurable nature.

The trade-off of custom objects that clients fully own the code, including security and maintenance. This means it carries more responsibility than using Archer's app builder to configure the platform. Used properly, custom objects are a powerful way to tailor Archer to your processes. 

We built the New UI with custom objects in mind. The goal of this article is to understand how classic custom objects can be refactored to work with the New UI, and how users can build new, powerful custom objects going forward.

Jump to the section that best fits your need:
Refactoring Classic Custom Objects
Building New Custom Objects

Refactoring Classic Custom Objects

Classic custom objects are JavaScript that interacts directly with the page's HTML structure. The New UI is built on a modern React framework with an entirely different underlying structure. This means that a custom object made on classic has nothing to attach to and will not function properly in the New UI. Instead of code directly interacting with the document object model (DOM), New UI custom objects run in an isolated iframe separate from the rest of the page.

The good news is that the New UI introduces Broadhead, which is a supported command framework that gives custom objects a stable, documented way to read and write data, call APIs, and drive workflow. Broadhead does not depend on the page's internal structure, so code written using Broadhead is less likely to break with future releases than classic custom object code ever was. 

→ Read about Broadhead on the Archer Help Center

Changes to Custom Objects in Application Builder

We recently made a change to the custom object in Archer's application builder to support a two-code model. When you open a custom object in the layout builder, you'll see two code boxes. The first, under Custom Object Properties, holds your existing Classic code and runs only for users in the Classic Experience. The second, New Experience Custom Object, is where you place the Broadhead version, and it runs only for users in the New UI. These two code inputs are independent, so you can refactor and test without changing the functionality for classic users.

Recommended Approach to Refactoring Custom Objects

Below are some steps we recommend when planning your migration to the New UI, if you have custom objects in place. 

1. Catalog Your Custom Objects

Identify every custom object in your environment and what each one does. Many of our clients have found that there is a native alternative to their custom objects. Common custom objects included showcasing workflow on the top of the screen, hiding the copy or add new buttons, or showcasing metrics at the top of the screen. Features like this and more are now native functions of the new UI, and should be leveraged rather than porting forward a custom object.
Retiring an object is always cheaper than rewriting it.

The goal of this step is to understand all of the custom objects and to identify their purpose. Then your team can determine if you can retire or refactor each custom object. Below is an example of what this step may look like:

2. Categorize by Function

Group the surviving custom objects by what they do: data display and formatting, field calculations or validation, API calls and integrations, or workflow actions. Each of these categories map to a Broadhead pattern, which will help us reuse our approach with similar objects rather than solving each one by scratch.

Below is an example of what the output of this exercise might look like:

3. Rewrite with Broadhead

Instead of rewriting your old custom objects line for line, we recommend that you rethink the approach. The classic custom object code would interact directly with the DOM. New UI custom objects uses Broadhead to interact with the platform through defined commands in a containerized iframe.

The logic usually carries over, but the mechanics are different. Use the Broadhead API documentation as the reference for available commands and actions.

→ Read about Broadhead on the Archer Help Center

4. Test Both Experiences.

Validate the Classic code still behaves for Classic users and the New UI code behaves for New UI users. Test in a non-production environment before promoting.

Need Help Refactoring? Call Professional Services

Refactoring custom objects is the part of migration where teams most often want a hand, especially when objects are numerous, complex, or undocumented. Archer Professional Services can assess your custom object inventory, recommend which to retire versus rewrite, and handle the Broadhead refactoring for you. If custom objects are a significant part of your environment, engaging PS early is the fastest path to a clean migration.

Learn more about our Professional Services Organization by talking to your account representative.

Building New Custom Objects

If you're building on the New UI without migrating anything from Classic, this is your starting point. You're working from a blank canvas with no legacy code to carry forward. To write custom objects, you'll need to learn more about using Broadhead. But first, use the steps below to add a custom object to the layout

Add a custom object to the layout. In Application Builder, expand the Layout Objects list in the left pane, then drag the Custom Object option onto the layout.

Write your code in the New Experience field. When you open the object's properties, you'll see two code areas. The first, Custom Object Properties (labeled Code), is for Classic Experience code, so you can leave it empty. The one you'll use is New Experience Custom Object, which runs for users on the New UI. You will enter or paste your code there.

Set the display setting. Choose whether the custom object should appear when users are viewing a record, editing a record, or both. 

Save, then test. Save the object and the layout, then test it in a non-production environment as a user on the New UI before moving it to production. Confirm it behaves correctly in both view and edit if you've enabled it for both.

A Simple Example

Say you want to validate the system to validate that a user enters a number within the proper range. The example below would help accomplish this. For this example, we will assume that we have a field that the user will use to enter in their number, and the ID of the field is '12787', which can be found in the field properties in Application Builder.

<script>
	const BUDGET_FIELD_ID = 12787;
	const MAX_BUDGET = 100000;
	
	broadhead.subscribe('form-values', (response) => {
	  const budgetValue = parseFloat(response.message[BUDGET_FIELD_ID]) || 0;
	
	  if (budgetValue > MAX_BUDGET) {
	    broadhead.sendAction('set-error', {
	      fieldId: BUDGET_FIELD_ID,
	      error: 'Budget cannot exceed $100,000'
	    });
	  } else {
	    broadhead.sendAction('clear-error', {fieldId: BUDGET_FIELD_ID});
	  }
	});
</script>

Broadhead is used in this example to read the form values, pull specific data, then send the user an error message, and when fixed, clear the error. Users could enhance this further by making the MAX_BUDGET variable dynamic based on another field or value.

The same patterns can be extended to more capable objects. You could use broadhead.fetch(...) to bring in data from an Archer API, or a workflow action to advance the record. 

The Broadhead reference in the Help Center is your guide to the full set of available commands. We also have a Free Friday Tech Huddle on custom objects for our New UI, as well as a presentation from Archer Summit on the same topic.

→ Read about Broadhead on the Archer Help Center
→ Watch the Free Friday Tech Huddle Session on Custom Objects
→ Read the presentation "Deep Dive Into New UI Custom Objects"

Back to the New UI Hub