Understanding Errors and Rejected Lines When Importing Data Via APIs

AnaplanOEG
AnaplanOEG
edited December 2022 in Best Practices

The objective of this article is to provide a quick explanation on the responses that APIs can provide when an import is submitted, in particular regarding the dump logs generated. This content is suitable for Model Builders comfortable with APIs.

We need to keep in mind what type of import we want to achieve. Indeed, the responses and the dumps will be different, depending on what you are trying to import; data in a module needs different indications than items in a list.

When importing data in a module, having the same code in the source will automatically aggregate data based on the code. When importing in a list, lines using the same code will be considered duplicates.

When Does an Import Create a Dump File?


Import in a Module

For the sake of clarity, we will use the following module as an example:

annejulie_24-1619721290044.png

In that module, you have:

  • Time: May 17 (we filtered on that month for simplicity)
  • 4 line items: 2 editable ones (Unit Sales by period, Amount to add) in blue and 2 calculated ones (Unit Sales, Current Alloc), which cannot receive data – in black.
  • 2 list members: MSFTE and GOOGLA

To update that module, we need to import data, as opposed to importing master data.

Let's use the following file:

 

annejulie_25-1619721323681.png

 

If you perform the import, there won’t be any error:

annejulie_26-1619721340085.png

‘Failed’ Error Message

Let's edit the month for one line with a spelling issue.

 

annejulie_27-1619721377489.png

You will get an obvious error:

 

annejulie_28-1619721389395.png

The log will be showing one line:

annejulie_29-1619721408389.png

Conclusion: when importing data into a module, if an identifier is invalid, the line containing this error will be listed in the dump of that action.

‘Ignored’ Error Message

There are 2 possibilities:

  1. Import into calculated line items.
  2. Import into elements already subjects to aggregation.

Case 1: Import on calculated line Items

Let's try to import data into line items that are calculated. We will use the following file:

 

annejulie_30-1619721441194.png

In that case, Current Alloc cannot be updated as it is the result of a calculation. The result will then be:

 

annejulie_31-1619721456608.png

There will be no dump if you click on ‘Details.’

 

annejulie_32-1619721471946.png

Case 2: Import on a consolidated level

Let's try to import data into a parent. We'll choose 'Q2 FY17' as a parent of a time member.

annejulie_33-1619721501124.png

Note: Current Alloc is a calculation and will ignore attempts.

 

We get the following response and no dump:

annejulie_34-1619721522637.png

Import Via API in a Module

We are reproducing the same steps as above through API calls; Let’s import data in a module with the incorrect mapping (spelling error Nay 17).

As seen below, the status is "Complete." (Line 18) as the import did go through.

 

annejulie_35-1619721549599.png

Rejected lines through APIs will only be generated for the lines that have wrong identifiers (like Nay 17 instead of May 17).

‘Ignored’ lines won’t be mentioned for line Items calculated or consolidated in a hierarchy.

Import in a List

Let's try to update the list that contains our two elements—MSFTE and GOOGLA.

The main difference with the previous case is that we will be targeting master data (lists and properties). Therefore, we will have dumps that will be slightly different from the previous case.

annejulie_36-1619721585982.png

Note: we will use the "Code Only" type of import.

annejulie_37-1619721615047.png

 

If we use the following import file, no issue will come up:

 

annejulie_38-1619721634994.png

And the API will send back that two elements were updated (even though no change occurred).

Wrong Code

Let’s introduce some errors to see the behavior.

Case 1: Duplicated Code

Let's add another line with an already-used code.

 

annejulie_39-1619721679922.png

In that case, we will get a warning (not an error!) that indicated that a row has already been processed with that key.

Why a warning? Because the first occurrence of the code has been successfully processed and then, technically, the import did go through and made changes.

 

We will then get a dump file with the rejected lines:

 

annejulie_40-1619721708239.png

Note that, unlike the module import, a new technical column, called ‘_ Status _’ is added to the dump. In that case, it is empty.

Case 2: Invalid Code

If we use the following file, we will generate a failure:

annejulie_41-1619721746555.png

 

In the dump file, we will get the rejected lines:

annejulie_42-1619721762132.png

Note that the ‘_ Status _’ column is not empty this time. 

If we look at the API dump:

annejulie_43-1619721798683.png

As you can see, the column ‘_ Status _’ contains an "E" as Error.

‘Ignored’ Error Message

Let's add a duplicated line, similar to line 2.

annejulie_44-1619721843391.png

In the API dump log, you will get an error line AND a rejected line.

annejulie_45-1619721867751.png

If we add another duplicated line:

annejulie_46-1619721887430.png

You will get a second rejected line:

annejulie_47-1619721908829.png

We can consider that the 2nd rejected line is an "ignored" error.

 

In the case of import into a list, when an error line is repeated several times, in the dump log, you'll get a first line in error and the other similar lines will be rejected.

 

Conclusion

Dump file format depends on the type of imports they are targeting: line items or lists.

Into lists, an additional column will help to distinguish if the line is the first error occurrence. For the other similar errors, they will be considered as "ignored" but related to the same first occurrence error. This explains why they appear in the dump file: we can consider that they represent the "ignored" lines of errors.

 

Did you like this content? Do you have other cases you would want to see added here?

Let us know in the comments thread below.

Contributing authors: Christophe Keomanivong and Nathan Lopez.

Tagged:

Categories