M3 API function

Use an M3 API function, or M3A function for short, to access M3 functionality. These are the types of M3 API functions available:

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

  • Repeating, when multiple data records are returned from M3.
    Note: To modify the number of records returned per MI Program, use SetLstMaxRec transaction. The scope of the SetListMaxRec transaction is only within the XMLTransform process.

    The M3A type is defined by the property Type.

    You can use a repeating M3A to 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 is not 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 is started 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 Russia-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 is displayed.

    If the M3 API that is not installed is called when starting the mapping, an error is displayed: The API <MI program name>.<transaction name> is not installed!. Then, the mapping is closed regardless of how the ErrorHandling attribute is set.