Mapping
Mapping is the process of taking data from the source project and applying the equivalent target project values to it, so that the project can be created in the business management system. If you are implementing the Project Ingestion API use case and not the BMS Integration use case, you will not need to develop anything around mapping - though knowing about the concept is useful.
Take a look at the sample response of the List projects call.
This project was created from an opportunity that only had one representation, it contained the values as they are in the source system. BeLazy copied these values to the project - you can see them under origin in the JSON response -, and enriched the project with two more representations: beLazy and destination. You won't need to use beLazy, all the relevant data are available for you in origin and destination. The destination representation will only ever include values that you uploaded into BeLazy, and prevent any unmapped data from causing errors. When you create a new project by accepting an opportunity, and there is a new, unmapped piece of data, BeLazy throws a red flag, displays a card on the user interface with instructions on how to resolve it, and the user can map the unmapped value to an existing data value in your business management system. The project is only generated once all invalid values are resolved. This removes the need to develop a robust error-handling logic.
How does this work?
Setting up the BMS values
Your business management system has data and identifiers, for example the list of languages and their codes, or the names of customers and their identifiers. If you open the BeLazy web application, navigate to the profile menu / Manage my business management system. You will see a list of values to upload in JSON format, containing objects that consist of a label and a value. As a developer, you can extract these lists from your business management system that you are integrating.
Every entry is a label-value pair. Labels (e.g. Spanish (Spain)) are what appear on the screen in BeLazy when you are mapping them. The value is the ID which is used by your BMS to refer to this item (e.g. 15). The value consists of the type, which is typically IntegerNumber or Text and the value which is the actual ID.
The BMS values are the allowed values in your BMS. These are the only values that BeLazy can fill the destination representation with.
Please refer to the Example JSON files section of the BMS Integration use case article for examples.
Automating the connection
When you add a connection in the BeLazy interface (usually a URL, username, password is enough), and BeLazy offers a connector for this systems and the credentials are valid, or if it is a workspace, the Automate command appears. When automating the connection, BeLazy reads out different possible values from the vendor portal by analysing some 100-200 jobs, and allows you to map these origin values to your destination values.
For example, the vendor portal may use the language code spa as source or target language for an opportunity. You always require the use of sublanguages for the Spanish language, and you know this customer wants to order the translation into the language that is called Spanish (Spain) in your BMS. The origin value will be spa. The destination value will include both Spanish (Spain) as label and the language's identifier, 15 as value.
The mapping engine in BeLazy works either by matching values between the two systems (such as language mapping), or on the basis of default values and exceptions based on metadata of the origin opportunity. Users can set up all rules in the user interface.
Automating the connection allows the user to map origin values, the values that come from opportunities, to destination values.
Generating the destination project
Opportunities do not have destination values. Destination values are generated when accepting an opportunity and turning it into a project. If there is an unmapped value, or some kind of other error during mapping, BeLazy prompts the user in a red flag to fix it. The project is only generated once the BeLazy user fixed the value mapping. Therefore you're unlikely to end up with unhandled exceptions, provided that your BMS value list is up to date.