Operation/Identification

A common design pattern in our API is to have tags called Operation and Identification which describe how various objects are processed.

Operation

The operation defines how the object should be handled. For instance, if you send in an order using ProcessOrder, you might wish to have the system behave in this way:

  • If the order doesn't exist, create it.
  • If the order exists, update it.
In that case, you would send in OrderOperation = CreateOrUpdate in the call to ProcessOrder.

If instead you always wanted the system to create a brand new order from your call, then you would send in OrderOperation = Create.

Common operations

  • Find - Find an existing object
  • Create - Creates a new object
  • Update - Updates an existing object
  • CreateOrUpdate - Updates the object if it exists, creates it otherwise
  • FindOrCreate and CreateNotUpdate - Uses existing object, creates if it doesn't exist
  • Clear - Clears reference to the object

Identification

The identification tag tells the system how it should identify existing objects. Depending on the object, there are different parameters to identify it by. For instance, an article might be uniquely identified by either its article number or its article name.

Example: articles

Identifying by article number

Let's say you call ProcessArticle with the following parameters:

  • ArticleIdentification = ArticleNumber
  • ArticleOperation = CreateOrUpdate
Then you must supply article number in the tag called ArticleNumber. When processing the article, the system will use the ArticleNumber tag to check if there is an existing article with the same article number. If it exists, then it will try to update that article. Otherwise it will create a new article.

Identifying by article name

It might be the case that you don't have article numbers, and you only have article names for your articles. You can call ProcessArticle with the following parameters:

  • ArticleIdentification = ArticleName
  • ArticleOperation = CreateOrUpdate
Now you must supply the article name in the tag called ArticleName. When processing the article, the system will use the ArticleName tag to check if there is an existing article with the same article name. If it exists, then it will try to update that article. Otherwise it will create a new article.

Example: order and inorder lines

See our article about how order lines and inorder lines are identified.