> For the complete documentation index, see [llms.txt](https://bxorm.ortusbooks.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://bxorm.ortusbooks.com/bxorm-2.x/getting-started/migration-from-cfml.md).

# ACF/Lucee Migration Guide

Migrating to BoxLang ORM from Adobe ColdFusion and Lucee

BoxLang ORM is designed to be compatible with existing CFML ORM code, but there are some differences and considerations when migrating from Adobe ColdFusion (ACF) or Lucee.

## Configuration Differences

There are several ORM settings which have been renamed OR the default value changed in `bx-orm`. Rename these settings in your configuration.

### Renamed Settings

| Setting name (ACF/Lucee) | Setting name (BoxLang) |
| ------------------------ | ---------------------- |
| `skipCFCWithError`       | `ignoreParseErrors`    |
| `cfcLocation`            | `entityPaths`          |

bx-orm does not read the old names. A setting under its old name is ignored, so rename it in your configuration.

### Changed Defaults

| Setting                                           | Lucee Default | ACF Default | BoxLang Default            |
| ------------------------------------------------- | ------------- | ----------- | -------------------------- |
| `ignoreParseErrors` (formerly `skipCFCWithError`) | `true`        | `true`      | `false`                    |
| `autoManageSession`                               | `true`        | `true`      | `false`                    |
| `flushAtRequestEnd`                               | `true`        | `true`      | `false`                    |
| `proxyLazyLoading`                                | `true`        | `true`      | `false` (no effect in 2.0) |

Set these explicitly if your application relies on the ACF/Lucee defaults.

### Database Inspection (`useDBForMapping`)

Adobe ColdFusion inspects the database by default to complete entity mappings. In BoxLang, `useDBForMapping` is `false` by default, so every entity must declare what it needs. If your entities leave out their `ormtype` or their id and rely on the table to fill them in, set it:

```js
this.ormSettings = {
    useDBForMapping : true
};
```

BoxLang then reads each existing table at startup and fills in the `ormtype` of untyped properties (from the column type) and the id of a root entity that declares none (from the primary key). Unlike Adobe ColdFusion, it does not infer foreign keys: declare relationships with their `fkcolumn`. See [Using the Database for Mapping](/bxorm-2.x/getting-started/configuration.md#using-the-database-for-mapping).

### Event Handling

As in Adobe ColdFusion and Lucee, ORM events only fire when `eventHandling` is `true`. With the default (`false`), neither entity event methods, the global `eventHandler`, nor `postNew` run. Earlier bx-orm versions fired events even without this setting, so set `eventHandling: true` if your application uses ORM events:

```js
this.ormSettings = {
    eventHandling : true,
    eventHandler  : "models.ORMEventHandler"
};
```

## Built-in Function Differences

Most of the built-in functions (BIFs) from other CFML engines are functionally identical in BoxLang. A few notable exceptions:

### `EntityLoadByPK()`

In ACF/Lucee, this BIF returns an array of entities by default, and you must pass a `unique=true` argument to return a single entity. In BoxLang, a single entity is returned by default. A boolean third argument (Lucee's `unique`) is accepted and ignored; in BoxLang the third argument is a struct of load options (`lock`, `timeout`, `skipLocked`, `readOnly`). To return an array of entities in BoxLang, use the `entityLoad` BIF instead, or pass an array of ids: `entityLoadByPK( "Automobile", [ id1, id2 ] )` returns an array in the order of the ids.

```js
// Lucee/ACF returns an array
var myAuto = entityLoadByPK( "Automobile", "1HGCM82633A123456" ).first();
// BoxLang returns a single item
var myAuto = entityLoadByPK( "Automobile", "1HGCM82633A123456" );
```

### `EntityNew()`

In ACF, a third argument `ignoreExtras` lets you ignore struct keys that do not match properties on the entity. In Lucee, this argument is called `ignoreNotExisting`.

In BoxLang, extra keys are always skipped: only keys that match a declared property are set, and other keys cause no error. A third argument is accepted and ignored, so ACF and Lucee code keeps working.

```js
var entityProps = { color: "Blue", nonExistentKey: "Blue" };
// no error: color is set, nonExistentKey is skipped
var myNewEntity = entityNew( "Automobile", entityProps, true );
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://bxorm.ortusbooks.com/bxorm-2.x/getting-started/migration-from-cfml.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.