When you create a Custom Integration in Aragorn, you define exactly what data Aragorn will send to the downstream system or vendor.

This is done in two steps:

This separation gives your organization control over both the structure of the file or payload and the data that leaves Aragorn.

For example, if a vendor expects the following fields:
​

you can create those exact fields in the integration specification and then choose which fields from your Aragorn project populate them.

Before configuring your mapping, obtain the field requirements from the system or vendor receiving the data.

Ideally, the vendor should provide a file specification, API specification, implementation guide, or field list that identifies requirements such as:

If the vendor requires fields to use specific names, create the fields in Aragorn using those exact names.

For example, if the vendor expects:

do not create:

unless the vendor confirms that the alternative name is supported.

If the downstream system does not require a specific field naming convention, you may create names that make sense for your integration.

The mapping page connects two sides of the integration:

Aragorn Project Fields → Integration Fields
​

The left side represents fields available from your Aragorn project whereas the right side represents the specification you created for the downstream system.
​

A mapping such as:

means when this integration runs, Aragorn will take the value from c_employee_id and send it to the downstream system as employee_id.

The source field and destination field do not have to have the same name.

Open the Custom Integration you want to configure and navigate to its Integration mappings page.

At the top of the page, you will see the project and integration involved in the mapping.
​

For example:

The page also identifies the current delivery behavior, such as:

From this page you can:

​

Select: Add or modify fields

This opens the Update custom mapping specification screen. The specification defines the fields that Aragorn is allowed to send through this particular integration. Think of it as the contract between Aragorn and the downstream system.

For each outgoing field, you can define its:

You can create fields in two ways: Use AI to auto-generate fields or Add field manually

If the vendor has given you a list of fields, you can use Aragorn to create the initial specification more quickly.

Select: Use AI to auto-generate fields

A window opens with a large text area where you can paste the field names.

For example:

Enter one field per line. Then select: Generate vendor fields

Aragorn will use the field list to generate the integration fields for you. This is particularly useful when a vendor provides a long field specification and you do not want to create every field individually.

Auto-generation should be treated as a starting point. Before saving your specification, review the generated fields against the vendor's documentation, including:

If the vendor provides strict implementation requirements, the vendor's specification should remain your source of truth.

To define a field yourself, select: Add field manually and the Add new field to specification window will open. Several configuration options are available.

Field Name is the name Aragorn will send to the downstream system. For example:

If your vendor specifies a required field name, enter it exactly as documented. The project field is your internal source. The integration field is what the receiving system sees.
​

Use Field Datatype to define the type of value that should be sent for the field. Examples shown in integration mappings include:

Choose the datatype that matches the downstream system's requirements.

Examples:

The datatype should be based on what the receiving system expects, not simply how users refer to the field.
​

Field Format lets you define format validation for the field. The interface supports using YYYY-MM-DD date type template or a regular expression (regex) for format validation. This can be useful when the downstream system requires a particular structure.
​

Use Max character limit when the receiving system restricts the maximum length of a field. For example, if a vendor states: Job Title must not exceed 100 characters.

you can configure:

If the vendor does not specify a maximum length, this setting may be left blank.
​

Use Field description to explain what the integration field represents. For example:

A clear description is especially helpful when:

Descriptions may also appear with the field on the mapping screen, giving administrators additional context while selecting the appropriate source data.
​

​

Some downstream systems require a field only under certain circumstances.

Use Field requirement criteria to define a conditional requirement.

The configuration follows a structure similar to:

This allows the specification to represent requirements such as:

or another condition defined by your implementation.

Use this section when the vendor documentation says something similar to:

This field is required when...

If the field is not conditionally required, leave the requirement criteria unconfigured.
​

Enable: Field must be included in data when the receiving system requires the field to be included in the outgoing data. Required integration fields are identified on the mapping page with a Required indicator.

You should make sure every required field has an appropriate Aragorn project field assigned before activating or relying on the integration.
​

Enable: Field value can be assigned to 'null' when the receiving system allows the field to be present without a value. There is an important difference between:

The field must exist and: The field must always contain a value.
​

For example, a vendor might require manager_email to exist in the payload but permit it to be null for employees who do not have a manager.
​

Follow the receiving system's requirements when configuring this option.
​

After completing the field configuration, select: Add field. The field is added to the integration specification and becomes available for mapping. Repeat this process for each field expected by the downstream system.
​

The specification screen includes: Integration should send changes only

When this option is not enabled, the integration can operate as a Full-file integration. A full-file integration sends the applicable mapped dataset according to the integration's delivery configuration.

Enable Integration should send changes only when the downstream process is intended to receive changes rather than the complete mapped dataset on every delivery.
​

This is commonly referred to as a change-only, delta, or incremental delivery pattern.
​

A full-file delivery could contain:

If only Employee 1003 changes, a changes-only process is intended to send the applicable change rather than resending the entire population.
​

Whether you should use Full-file or changes-only delivery depends on what the receiving system supports.
​

Confirm the expected delivery behavior with the vendor before enabling changes-only delivery.
​

The specification screen also contains: Sort data by

Use this configuration when the outgoing integration data needs to be ordered by one or more fields.

The number shown with Sort data by indicates how many sorting selections are currently configured.
​

Sorting is typically only necessary when the downstream system requires records in a particular order.
​

If the vendor does not specify a sorting requirement, you generally do not need to add one.
​

​

Once your integration specification exists, return to the Integration mappings page.

Each row represents an outgoing integration field. The right side shows information such as:

The field name is the name that will be sent to the downstream system. The value after the separator identifies its configured datatype.

On the left side, select the Aragorn project field that should populate it.

Consider the following mappings:

With this configuration, Aragorn does not rename your project fields. Instead, the mapping tells Aragorn: Take the value from this project field and place it into this integration field when sending data downstream.
​

For example:

The receiving system sees:

It does not need to know that the field is called c_pto_start_date inside your Aragorn project.
​

The mapping should be treated as a deliberate data access boundary. Your Aragorn project may contain significantly more information than the vendor needs. Your integration specification should contain only the fields needed for that purpose, and only the appropriate Aragorn fields should be mapped.
​

The existence of data inside your Aragorn project does not mean that it must be sent to every connected system.
​

Use the minimum data necessary for the downstream process as this provides a clear governance model

The Custom Integration specification provides an explicit layer between your Aragorn data and the external system. Consider an Aragorn project containing 100 fields.

If your custom integration specification contains only 15 fields, the integration is designed around those 15 outgoing fields rather than automatically exposing every field in the project. The mapping then determines which approved source fields supply those 15 values.

This gives administrators control over: