M3 API

Use an M3 API function, or M3A function for short, to access M3 functionality. The M3A function can be of two types:

  • Single, when a single data record is returned from M3.

  • Repeating, when multiple data records are returned from M3.

    The M3A type is defined by the property Type.

    A repeating M3A must control a loop because multiple data records are returned from M3. The main objective is to create repeating elements in the output document based on the result returned from the M3 API call.

    You can add M3 API in a loop using the wizard. Follow these guidelines:

    • If you drop M3 API in the first element of a loop, you can only select Repeating M3 API functions.

    • If you drop M3 API in other locations in a mapping, you can only select Single M3 API functions.

An M3 API function call can fail and the action taken is controlled by the ErrorHandling attribute which can have these values:

  • Use Exit map on M3 NOK to stop the current mapping operation.

  • Use Exit loop on M3 NOK to stop the current loop operation in progress.

  • Use Ignore M3 NOK to ignore the error.

If the M3 API may not be installed at the customer, for example a country specific API, and the M3 API is never called if it is not installed, use the API Installed attribute which can have these values:

  • Use Required to require the M3 API to be installed when generating or publishing the mapping. This is the default setting.

  • Use Optional if the mapping can be executed without calling this M3 API.

    The M3A function must be placed within an If widget or within a Loop in the mapping so that it is not used if the customer has not installed the M3 API. For example, if the M3 API is a Russian specific API, the M3 API must only be called when the current M3 Division is set up for Russia.

    If the M3 API is not installed or not updated, when the mapping is generated or published, only a warning will be given.

    If the M3 API that is not installed is called when executing the mapping, an error will be given: "The API <MI program name>.<transaction name> is not installed!". Then, the mapping will exit, regardless of how the ErrorHandling attribute is set.