Mapping lifecycle

The concepts in this section explain the mapping generation, publish, and activation lifecycle states of a mapping.

On an overview, this diagram shows that you use Business Document Mapper to create a mapping, activate it in grid Management Page, then use it in Partner Admin tool. You must activate the mapping first, then reload the cache to activate the Partner Agreement using the mapping.

Process steps Details
1. Create a mapping.

  • Create a mapping in Business Document Mapper, or import an existing mapping from a .zap file or from a mapper server.

  • The mapping now exists as files in your Eclipse workspace.
2. Save the mapping to the mapper server.

Optionally, save the mapping to the mapper server without generating or publishing it.

  • The mapping now exists as metadata in the mapper database.

  • If the mapping uses custom JARs, these are also stored in the mapper database.

  • At this stage, if this is a new mapping, no runtime mapping class exists.
3. Generate the mapping.

Optionally, generate the mapping. The mapping is automatically saved in the mapper database.

  • The mapping now exists as metadata in the mapper database.

  • If the mapping uses custom JARs, these are also stored in the mapper database.

  • At this stage, if this is a new mapping, no runtime mapping class exists.

  • A runtime mapping class is generated and compiled, but the runtime mapping class is not inserted into the mapper database. A Java file is written to the file system, though.

  • EC data translations are parsed, but metadata is not inserted or updated in the mapper database.

Generate is used for testing purposes only. Use this to verify that you can generate the mapping, compile the mapping, and that the EC data translations are correctly defined.

Generate does not affect runtime. Although, the mapping metadata in the mapper database is updated.
4. Publish the mapping.

The mapping is automatically saved in the mapper database.

  • The mapping now exists as metadata in the mapper database.

  • If the mapping uses custom JARs, these are also stored in the mapper database.

  • A runtime mapping class is generated and compiled.

  • The runtime mapping class is inserted into the mapper database as Current Source.

  • A Java file is also written to the file system.

  • IEC data translations are parsed and metadata is inserted or updated in the mapper database.

The mapping is now in the Inactive state and ready for activation.
5. Activate the mapping
Note: This only applies to EC. In ION, a mapping is automatically activated when a Document flow that uses the mapping is activated.

  1. Select Grid > (MEC) Application Management Page > Server > Mappings.

  2. Click Activate for the mapping.

    • The runtime mapping class is now compiled and put into the classpath.

    • You can now use the mapping in Partner Agreements.

    • If the mapping uses custom JARs these are also put into the classpath.

Note: A mapping cannot be used in Partner Agreements until it is activated.

If you use an inactive mapping, these error messages may be displayed:

  • NoClassFoundException

    This error is displayed if a Partner Agreement uses an inactive mapping in runtime.

    Resolution: Activate the mapping and then reload the cache to activate the Partner Agreement using the mapping.

  • Unable to find source code for mapping id '<id>'

    This error is displayed if the mapping used by the XML Transform process in the agreement is published but is not activated.

    Resolution: Activate the mapping and then re-run the message.
6. Update the mapping in Business Document Mapper.

  • Use this to update the mapping in Business Document Mapper.

  • The updated mapping now exists as files in your Eclipse workspace.

    Note: If you change the mapping’s version number, the updated mapping will be handled in the same manner as a new mapping. See step one.
7. Save the updated mapping to the mapper server.

Optionally, save the mapping to the mapper server without generating or publishing it.

  • The updated mapping metadata is now stored in the mapper database, but the runtime mapping class is still generated from the old Current Source.

  • If the mapping uses custom JARs, these are also stored in the mapper database. If custom JARs are added or removed the mapper database is automatically updated accordingly.
8. Generate the updated mapping. This step is optional. See step three.
9. Republish the mapping.

The mapping is automatically saved in the mapper database.

  • The mapping now exists as metadata in the mapper database.

  • If the mapping uses custom JARs, these are also stored in the mapper database. If custom JARs are added or removed, the mapper database is automatically updated accordingly.

  • A new runtime class is generated and compiled.

If the mapping is in Active or Republish state:

  • The new runtime mapping class is inserted into the mapper database as Pending Source.

  • The Current Source is not overwritten.

    Note: The Current Source is still used in runtime.

    Even if you restart EC or if new EC Server nodes are started Current Source is used.

    To use the Pending Source, you must reactivate the mapping. This message is displayed in the Business Document Mapper Mapping Console when (re)publishing an active mapping:

    "Mapping 'mapping_name' version mapping_version 
is currently active, your changes will not take 
effect until the mapping is reactivated"

If the current mapping is in Inactive state:

  • The new runtime mapping class is inserted into the mapper database as Current Source.

  • The previous Current Source is overwritten.
10. Reactivate the mapping.
Note: This only applies to EC. In ION, a mapping is automatically reactivated when a Document flow that uses the mapping is activated.

  1. Select Grid > (MEC) Application Management Page > Server > Mappings.

  2. Click Reactivate All Republished for the mapping.

    • The Pending Source is moved to Current Source.

    • The runtime mapping class is compiled and replaces the old class in the classpath.

    • If the mapping uses custom JARs, these are also replaced in the classpath.

This operation applies to all EC nodes that execute runtime mappings. After this operation, Pending Source no longer exist, it is moved to Current Source. The mapping is now in Active state again.
11. Inactivate the mapping
Note: This only applies to EC. In ION, a mapping is automatically inactivated when all Document flows that use the mapping are inactivated.
Note: To avoid ClassNotFoundException error at runtime, you must remove the mapping from all Partner Agreements and reload the cache before performing this operation.
  1. Select Grid > (MEC) Application Management Page > Server > Mappings.
  2. Click Inactivate for the mapping.

    • The runtime mapping class is removed from the classpath.

    • If the mapping uses custom JARs, these are also removed from the classpath, if not used by other active mappings.

    • The mapping is now in Inactive state.

    • The latest source code for the runtime mapping class is stored as Current Source.

When you restart EC, the previously loaded runtime mapping classes are automatically compiled and added to the classpath. Custom JARs are also added to the classpath.

When you start EC, the Current Source is used.

If a mapping was republished, so that Pending Source also exists, you must reactivate the mapping in the new EC session to run the latest version of the mapping source code (and also the latest custom JARs). To reactivate, a republished mapping requires an explicit user action.

This diagram shows the mapping states and the available actions:

This is a screenshot from the Grid Management Pages for EC:

Under the Action column, select a state to invoke for the mapper in that row.

On the bar at the top, select a state to invoke for all or certain mappings in the table.

These are the mapping lifecycle states:

Activate

  • Activate All Inactive to activate only the mappings in Inactive state.

  • Activate/Reactivate All to activate all mappings, both when the mapping is inactive and when the mapping is republished, but not yet reactivated.

  • Reactivate All Republished to reactivate all republished mappings.

Inactivate

  • Inactivate All Active to inactivate only the mappings in Active state.

  • Inactivate All to inactivate all mappings, both when the mapping is active and when the mapping is republished, but not yet reactivated.

  • Inactivate All Republished to inactivate all mappings that are republished and already reactivated.