Explaining Tips and Tricks for Implementation

Any customization must be developed as a separate component as an MDK project. It will make it easier to maintain and upgrade in the future.

When creating a .cim file, the application name and project name are important as they define the folder structure of where your component definitions are. Your definitions must be inside <ProjectName>/<ApplicationName>/ and must follow the exact structure.

• Make sure the component.cim file is imported into the SAP Service and Asset Manager project.

• When multiple components exist, make sure all the component.cim files are imported as well.

• Make sure you have specified the metadata override definition is in the component.cim file.

• When updating the base component, make sure to run find_comp_conflicts.sh to check if any of the modified files are being overridden. If there are any, make sure to update those files in the corresponding component.

• Localization files must be specified in the component.cim file as well. If a language file is not specified in the .cim file, only the base product strings will be localized.

• Create common methods in library files that can be reused.

• Do not override existing methods but create a copy of the same method with your customization. This is especially true when you are trying to change the methods present in the Common folder as they may impact on other components of the application.

• Date can be stored in the state variable like ClientData or any static js class globally, but it is not recommended to overload this. For the ClientData keep it at a page level, if needed.

• State variables are used to save rule data that must persist during a session. When a state variable is no longer necessary, it must be removed using the clearFromClientData routine in the common library. This frees up the memory that was being used, and prevent unexpected logic errors in code that use these state variables.

• When reading data from entity sets, only retrieve the properties that are necessary. Do not inefficiently return every property. Accomplish this by using a $select clause in the OData query itself, or populating the properties parameter on the read function with a string array of property names to retrieve.

• Two-button message dialogs can be displayed and handled programmatically using the showWarningDialog common library routine. This is typically used for handling transaction validation before saving data when the user must decide based on the message, and either choose 'OK' or 'Cancel.' This method is also used when the user must confirm whether they really want to discard some data. showErrorDialog is another common routine that only allows the user to click a single button to dismiss the message dialog. This routine will always return a false value that fails transaction validation.

• Knowing whether the current object on a page is local (new) to the offline database or was retrieved from an entity set in the cloud is an important distinction that determines what functionality is allowed around this object. There are common routines set up to determine this. OData rows in SSAM have a ReadLink associated with them. This readLink contains internal information about the row. The current object's ReadLink can be pulled from the page in any of the page's rules. Using the OnPageLoad rule, the following code returns the ReadLink: let currentReadLink = libCommon.getTargetPathValue(pageClientAPI, '#Property:@odata.readLink'); Determining if this ReadLink is local can be done using let local = libCommon.isCurrentReadLinkLocal(currentReadLink); If 'TRUE' is returned, then the object is new and was added locally from the client device. If 'FALSE' is returned, then the object was downloaded from the entity set in the cloud.

• Validation rules can be assigned to create and update entity actions in SSAM and are used to halt execution of the action when one or more logic errors are detected by the rules before the new data being saved. MeasuringPointLibrary.js is a good resource for learning to write complex validation rules and mixing in-line with dialog-based validation on the same screen. Inline validation must be used when a particular field on screen needs attention. A different colored message can be displayed under the field indicating the problem and allowing the user to correct it. An example of an inline validation rule is one to catch the maximum field length being exceeded by the user's data entry: "Maximum field length: 40". A dialog-based validation rule will pop a warning dialog that the user must either accept or cancel, or it displays an error that the user must acknowledge before proceeding. Dialog-based rules must be used when no fields or more than one field are involved, or when the message is unusually long, or when a user choice is necessary to proceed. Examples include: "Daily total would exceed 24 hours." and "Counter reading is the same as previous reading." When a complex logic-based error or warning is detected, it is preferable to use a dialog-based message. Use inline messages for simple one field validation that can be easily communicated with a short inline message.

• When using target paths in metadata, be aware that an undefined target path result may cause unexpected results in the MDK rendering on the page.

• "Target" in metadata lists can be an OData Entity Set or an OData collectionExample: "MyWorkOrderHeaders" or "#Property:@odata.readLink}}/Operations" are both valid, given Operations is a collection of a MyWorkOrderHeader object. However, be aware that single OData entities will not be accepted by a list (there is no current way to bind a single entity to a list view that renders only a single item).

• #Property segments in target paths map directly to the underlying JS object's properties exposed to a rule, if one is placed instead of a target path.

• Target paths and text can be concatenated. For instance: "Order ID {{#Property:OrderId}}" is a valid use case; however, note the double curly braces separating the target path from the text literal. This will also work for i18n localization: $(L, order_id_x, {{#Property:OrderId}}) where order_id_x=Order ID {0}.

• Keep internal data formats for numbers, dates, and so on, separate from display formats. Use the Localization for formatting data in pages and rules. The Localization functions provided by the MDK are there for more than displaying localized strings.

• If you are changing the image of Action Bar, you need to rebuild the app as opposed to just redeploy the bundle as Nativescript has limitations on the "ActionBar" and "Toolbar" customizations.

• Make the utilization of the action results if the data is needed for further processing. For example, using the action result data for conditional page navigation.

• Make sure to set the create or update links in the create or update action to be in compliance with the database schema.

• For any batch that handles multiple transactions in a create or update actions make sure to set the header OfflineOData.TransactionID is to a unique value on every chain of actions so that all of the create or update transactions processed in one batch.

• Make sure for every transaction that you create has an associated navigation action in the ErrorArchiveAffectedEntityNav.js to update a failed transaction upon a delta synchronization.

• Use the MS VSCode extension from MDK which gives the ability to debug the project.

• If debugging is done through the bundle.js, make sure to have a proper(unique) name for each method, so when trying to debug a method, it can be easily found in bundle.js.

• Always rebundle after updating the code; otherwise, the bundle.js will not have the latest changes. Add "–watch" to your project, so the bundle.js will automatically refresh whenever there are code changes.

• Note that the page binding properties with the specified "Target" and "QueryOptions" happen before the "OnLoaded" method.

• Turn on the activity logging on the client to debug a client issue. The log level can be set to different types, and all the information is written to filename.txt. The file can be accessed through iTunes and can be further investigated to debug a client issue.

• For any missing data for entity sets after an initial synchronization of the client, make sure you have defined all the entity sets in the InitializeOfflineOData.action and DownloadOfflineOData.action.

• Use ILOData, Sybase SQL Anywhere or any other DB tool to inspect the data being downloaded into the entity sets. ILOData tools give the capability to query the entity sets, and its relational entity sets similar to the native script query.

• To trace the initial or delta synchronizations for any user, log in to the SAP system, and use the /IWFND/TRACES tcode.

• The onboarding URL is the combination of the settings found in your cloud cockpit. If you don't see the "Start" button inside the app upon clicking the URL, your URL may have not been configured correctly.

• After the onboarding, if you don't see "Application Initialized" banner message, then your app may not have been registered for "Push" notification.

• If you see an error message right after onboarding starting from "Service unavailable..." then the problem is with the back end that your application is consuming. You may also want to see if all the entity sets are assigned to UserPersonas and UserSyncGroupDetails Entitysets.

• The localization of the strings you see during Onboarding is controlled by BrandedSettings.json file under "OnboardingCustomization" so make sure all your onboarding strings are present in that file.

• You can change the content of "EULA", that is, an End User License Agreement page that you see during onboarding from App_Resource/iOS folder. You must rebuild the app to see the changes.

• Make sure that the imported project is set as the Mobile Development Kit as the project type in order to enable the project in the MDK view and the additional features of MDK. This can be done through the project settings.

• To enable the MDK view and the additional feature of the MDK, in the project settings, set the project type of the imported project as the Mobile Development Kit.

• Take advantage of the MDK's Object browser, rule editor, or any new feature MDK delivers.

• In the case of multiple developers developing the app, make sure a git repository is set up. Also, it is recommended that each developer has his own instance of a mobile server set up so that each developer deploys their own metadata changes to their own mobile service, but still can check in their code to the same git repository. By doing this, the developers will not be overwriting each other changes during the LCMS update using a single instance of a mobile service.

• In the case of multiple projects, deploying the metadata with multiple projects to a single instance of the mobile service is not recommended.

• To ensure that the metadata is in synchronization with the SAP back end, make sure the destination connection is properly configured to the oData Offline configurations(that contain the schema changes), so that the destination reads the oData services from the Mobile Add-On in the correct order and build the object schema in the correct format.

• If there exists any missing entity sets, errors, or any new changes like adding entity sets or properties in the entity sets or navigation relations to the entity sets that correspond to the SAP Backend schema changes, go to the AssetManager.service file and click the refresh objects button to rebuild the objects from the mobile service. In doing so objects will be rebuilt with the latest schema from the mobile service. Also make sure that Service URL, Application ID and Destination Name are correct and properly set up on the Mobile Services cockpit.

• Make sure any custom entity sets are assigned to a Feature and the Feature is assigned to Persona. Verify the UserPersonas and UserSyncGroupDetails Entityset to make sure the custom entity set is properly assigned to the Persona.

• When deploying metadata changes to the mobile service, it is recommended to run the metadata validator. (The deployment does not stop if any errors exist in the metadata).

• For any metadata errors that are related to mdk controls, extensions, javascript syntax and so on. make sure you update the metadata references based on the mdk documentation with respect version of the controls, extensions and so on.

• Currently, MDK does not support extra languages by just updating the i18n properties files from the WebIDE/BAS. The client must be rebuilt every time a new language string is added.

• Currently, when changing the extensions, the client has to be rebuilt.

• Adding new icons and images can be done through the WebIDE/BAS. The app will render the new screens with the new icons after the LCMS update. Use .pdf vector images over .png for better rendering quality on all screen sizes.

• After deploying your changes to the mobile service, you can relaunch the app to trigger an LCMS update and see your changes right away.

• When importing your SAP Service and Asset Manager Project, delete the SIGNATURES.SMF file wherever it's found.