---
title: "insertOFMLArticle"
slug: "api/basket/operations/insertofmlarticle"
sidebar:
  order: 430
---

<a id="ref-4aca725dabe5"></a>
<a id="ref-6b21dd8ff549"></a>
<a id="ref-00d353e69205"></a>

## Synopsis

```text
BItemId insertOFMLArticle(SessionId sessionId,
    BItemId fatherId,
    BItemId beforeId,
    InsertInfo insertInfo,
    InsertArticleOptions* options)
throws BasketServiceFault;
```

See also: [BItemId](/pCon/configuratorOnline/specs/api/basket/types/bitemid#ref-bccb6c926e5b), [SessionId](/pCon/configuratorOnline/specs/api/session/types/sessionid#ref-02e397c8fdb4), [InsertInfo](/pCon/configuratorOnline/specs/api/basket/types/insertinfo#ref-71f4243a693d), [InsertArticleOptions](/pCon/configuratorOnline/specs/api/basket/operations/insertarticleoptions#ref-f9308300ee96), [BasketServiceFault](/pCon/configuratorOnline/specs/api/basket/faults/basketservicefault#ref-d5adb74faa1b)

The `insertOFMLArticle` operation inserts a new OFML article item into the basket item tree maintained by the basket service for the session identified by the `sessionId` parameter.

The `fatherId` parameter, if not the null-UUID, must identify the basket item that will become the parent of the new OFML article item. If `fatherId` is the null-UUID (§[UUID](/pCon/configuratorOnline/specs/guide/web-service-interfaces/common-type-definitions/uuid#ref-2a898bc98aaf)), the root item of the basket item tree will be used as the parent item.

The `beforeId` parameter, if not the null-UUID, must identify an existing basket item. If this item is a descendant of the basket item that has been selected as the parent of the newly inserted item, then the new item will be inserted in front of the parent’s child which is either equal to the item identified by `beforeId`, or an ancestor of this item. Otherwise (if `beforeId` is a null-UUID, or if the basket item identified by `beforeId` is not a descendant of the parent item) the new item will be inserted as the last child of the parent item.

The `insertInfo` parameter specifies the OCD article to be inserted. For more information see §[InsertInfo](/pCon/configuratorOnline/specs/api/basket/types/insertinfo#ref-71f4243a693d).

For attachment modes other than `None`, the item specified by the `fatherId` passed to the 'insertOFMLArticle' operation must be an basket article item that is part of a composite article.

(Note that a composite article may consist, in the most trivial case, of a single item. Also note that its usually not possible to insert an arbitrary article into a particular composite article. Either the composite article must be a special composite article that accepts any kind of article item (i.e. some kind of partial planning), or the composite article and the article to be inserted must have been designed to be used together.)

**planar**

<a id="ref-137879d7cbd8"></a>

```text
enum PlanningDirection{
    Right_Front,
    Right_Back,
    Left_Front,
    Left_Back,
    Front_Right,
    Front_Left,
    Back_Right,
    Back_Left}
```



`Default:` `Right_Front`

**<a id="ref-f20e9b1290f0"></a>spatialPlanningDirection=`Horizontal|Vertical`**

`Default:` `Horizontal`

Specification of planning directions only affects insertion into a composite article. If the new article is inserted as a stand-alone article, the planning directions are ignored.

**`strictVarCode=true|false`**

`Default:` `false`

- The `strictVarCode` flag affects OFML article instantiation as follows:

  - If false, OFML method `setCreationMode(0)` is called before the article is instantiated. Once the article has been instantiated, its configuration is restored using OFML method `setXArticleSpec()`. Finally, OFML method `assignDefaultPropValues()` is called to apply custom configuration profiles (not implemented right now).

  - If true, OFML method `setCreationMode(1)` is called before the article is instantiated, and its configuration is restored using OFML method setupConfiguration(). There is no call of OFML method assignDefaultPropValues(), so the variant code of the inserted article should conform to the specified variant code.

**`migrate=true|false`**

`Default:` `false`

If option `strictVarCode` is set to `true` then this option can be used to allow insertion of an article even if the configuration specified by the variant code is not supported by the product data in use, and thus cannot be restored exactly[^1]`.`

The operation first searches registered catalogs for the requested article. If the supplied insert information contains a catalog identifier, only this catalog is considered, and the catalog and article packages, if specified, must be part of the catalog. Otherwise, if either a catalog package and/or an article package has been specified, the operation considers the set of catalogs that contain the specified package or packages. Otherwise, the insert information must contain a commercial manufacturer identifier, and the operation considers all catalogs containing articles for this manufacturer.

If, at this point, no catalogs could be determined, the operation fails. Otherwise, if there is more than one eligible catalog, the catalogs are sorted according to their validity, release date, and the current date[^2]. The sorted list of catalogs is searched for the first catalog containing at least one catalog entry matching the given series (if specified), article package (if specified) and base article number. Subsequent catalogs are not considered.

If multiple catalog entries are found, and a catalog package is specified, and at least one of the found catalog entries originates from the specified catalog package, then the set of catalog entries is reduced to the set of entries originating from the specified catalog package.

If, at this point, the remaining catalog entries reference OFML articles from different packages, the insert operation fails[^3].

Finally, from the set of remaining catalog entries, the ‘best’ catalog entry is chosen to be inserted[^4].

The inserted basket item is of type `Article`, `Aggregate`, or `PartialPlanning` (§[BasketItemType](/pCon/configuratorOnline/specs/api/basket/types/basketitemtype#ref-5d3667cadff0)).

Note that the insertion of an OFML article may result in more than one new basket article item[^5].

A [`BasketServiceFault`](/pCon/configuratorOnline/specs/api/basket/faults/basketservicefault) is returned if any of the following conditions occurs:

- The `sessionId` parameter is not a valid string representation of an UUID or does not represent an open session.

- Either the `fatherId` or `beforeId` parameter does not represent an UUID.

- Either the `fatherId` or `beforeId` parameter does not identify a basket item and is not the null-UUID.

- The basket item identified by the `fatherId` parameter does not permit child items.

- If the catalog ID, if specified, does not adhere to the syntax of OFML catalog identifiers or does not identify a catalog referenced by the current session configuration.

- If the catalog package ID or article package ID, if specified, does not adhere to the syntax of OFML package identifiers, does not identify a package referenced by the current session configuration, or, if a catalog has been specified, the referenced package is not part of the catalog.

- No base article number has been specified.

- If the Online Configurator was not able to find a catalog entry matching the given insert information.

- There was some error during the actual process of inserting the OFML article. There are too many reasons for the insertion process to fail to describe here, but they usually originate from some product data error.

[^1]: <a id="ref-66cdfd7859aa"></a>This condition manifests itself with a `BasketServiceFault`, with `egr.eai.basket.ArticleMigrationRequiredException` as its cause.

[^2]: At present, the sort order is as follows: valid catalogs come first, followed by catalogs not yet valid, followed by catalogs no longer valid. Within each group, more recently released catalogs come first.

[^3]: This can not happen if an article package has been specified.

[^4]: The selection of the ‘best’ catalog entry is based on the comparison of the catalog entry’s variant code and the specified variant code, if any. The actual algorithm used for the comparison is implementation-defined.

[^5]: The best example is the insertion of a meta type where the meta type and main child both require their own order position.
