The Mirata Forms OData Interface Layer (FOIL) is an SAP Business Technology Platform (BTP) application implemented using the SAP Cloud SDK for JavaScript and the NestJS platform.

Mirata Forms functionality can be tightly integrated with an SAP Mobile Development Kit (MDK) application, such as SAP Service and Asset Manager. This is accomplished using a Mirata MDK control extension that is built into a custom branded version of the MDK Client. Custom metadata is used to interface the base version of the MDK mobile application with the Mirata MDK control extension and with the Mirata cloud-based data services.

1.2 Purpose

The SAP MDK mobile platform only allows for the exchange of data with an OData-based data source. The purpose of the Mirata FOIL application is to implement an OData data interface layer between a “mobile destination” of an MDK application deployed to BTP Mobile Services and a Mirata RESTful cloud-based API endpoint. FOIL receives HTTP-based OData query and data modification requests from BTP Mobile Services and makes the appropriate corresponding RESTful API call to the Mirata API endpoint specified by the MDK application’s destination definition. FOIL then receives JSON-formatted data from the Mirata API endpoint, transforms it into JSON data that meets on the OData v2 specification, and returns the data as a response to the original OData-based HTTP request received from BTP Mobile Services.

The Mirata FOIL application has two BTP service dependencies. The first is an XSUAA (eXtended Services for User Account and Authentication) service. The XSUAA service provides an OAuth/OIDC interface to BTP applications that require a user authentication service, and a SAML interface to an identify provider (or "IdP") service. Note that SAP BTP accounts provide a default trusted SAML-based interface to SAP's standard IdP (SAP ID Service). However, this interface is typically replaced with a SAML-based interface to a company-managed IdP. 

A “trust relationship” is also established between the Mirata cloud-based IdP and the BTP IdP, such that the Mirata IdP recognizes and accepts users authenticated by the BTP IdP. The XSUAA service that is created during the FOIL installation manages the exchange of information in this trust relationship. This IdP trust configuration enables the FOIL application to authenticate with the Mirata IdP service on behalf of an MDK mobile application user (who has previously authenticated with the BTP-managed IdP) when Mirata Forms data is requested by a Mirata Forms-enabled MDK mobile application.

The other BTP service required by a Mirata FOIL application is a "destination" service that maintains and provides data used to establish a connection to a Mirata cloud-based API endpoint.

1.3 Prerequisites

2 FOIL Installation Procedure

2.1 Preparing the FOIL Installation Software

The FOIL installation software is provided in a Zip archive file (foil.zip). Expand this archive file into an empty file system directory. 

Note: In the upcoming installation procedures, this directory is referred to as the “Mirata FOIL software directory”

2.2 Editing the FOIL Configuration Files

The upcoming installation procedures require editing a FOIL configuration file. The text-based configuration file is composed of a JSON (JavaScript Object Notation) object, and all edits to the configuration file must conform to proper JSON syntax.

2.3 Configure the FOIL XSUAA Service

2.3.1 Configure the Redirect URIs

Before building and deploying the FOIL XSUAA service, its configuration file must be updated with information specific to your company's BTP account. Specifically, the Server API URL from the Mobile Services service instance that will host the Mirata Forms-enabled MDK mobile application must be obtained and added to the formsxsuaa.xssecurity.json configuration file. If multiple Mirata Forms-enabled MDK mobile application instances are being hosted, the Server API URL from each mobile application instance must also be added to the same configuration file. If a new Mirata Forms-enabled MDK mobile application instance is deployed to BTP Mobile Services after the FOIL XSUAA Service has been installed, the same configuration file must be updated accordingly, after which the FOIL XSUAA Service must be updated accordingly.

To avoid defining multiple Server API URL entries in the formsxsuaa.xssecurity.json file, the * (asterisk) character can be used as a "wildcard" to qualify multiple mobile applications published to the same Mobile Services instance. Typically, the first segment of each Server API URL is specific to the mobile application, and the remainder of the URL is common to the hosting Mobile Services instance. Inserting an * (asterisk) in place of the first URL segment establishes a single entry in formsxsuaa.xssecurity.json that covers all current and future Mirata Forms-enabled mobile applications that may be added to the Mobile Services instance.

For example, if the Server API URLs for three Mirata Forms-enabled MDK mobile applications published to the same Mobile Services service instance are...

https://asset-manager-forms-dev.cf.us01.hana.ondemand.com

https://asset-manager-forms-qa.cf.us01.hana.ondemand.com

https://asset-manager-forms-prod.cf.us01.hana.ondemand.com

...then the URL below (which utilizes the * wildcard character) will qualify all three URLs above...

https://*.cf.us01.hana.ondemand.com

The Server API URL assigned to an MDK mobile application published to a Mobile Services instance can be obtained as follows...

1. Navigate to the BTP subaccount space that will host the FOIL application instance
2. Expand the Services (vertical) tab
3. Select the Instances (vertical) tab
4. In the Service Instances table, identify the row of the Mobile Services instance that is hosting the Mirata Forms-enabled MDK mobile application and select the Instance name (which is also a hyperlink). Authenticate with Mobile Services if needed.
5. On the resulting Mobile Services page, select the APIs (horizontal) tab
6. The Server API URL is listed in the table at the bottom of the resulting tab page

1. Note the "Copy to Clipboard" button to the right of the URL

Note: As each Server API URL is added to the forms-xsuaa.xs-security.json file, the characters /login/callback must be appended to the URL.

Each modified Server API URL must be added as a "string" to the JSON array of the redirect-uris key in the project file forms-xsuaa.xs-security.json. This array comes pre-configured with one or more entries. 

Note: The existing array entries pertain to the Mirata IdP service and must not be modified (unless directed to do so by Mirata support personnel).

The following image provides an example of the forms-xsuaa.xs-security.json file contents after adding the three Server API URL examples provided earlier (with /login/callback appended to each one)...

2.3.2 Configure the Token Validity Settings

In the project file formsxsuaa.xssecurity.json, the tokenvalidity and refreshtokenvalidity keys of the oauth2-configuration object together dictate the time that will elapse before the user is required to reauthenticate with the mobile application. Both key values define a duration in seconds. The tokenvalidity key specifies the duration a newly issued, or newly refreshed, ID token remains valid. The refreshtokenvalidity key specifies the duration (starting from token issuance) that an expired ID token may be refreshed (i.e.– renewed) without requiring the user to reenter login credentials. When the ID token expires, and the refresh token’s validity period has also expired, the mobile application user will be required to reenter username and password credentials upon performing the first interaction with the MDK mobile application that requires a corresponding action be performed by BTP Mobile Services.

Note that the tokenvalidity key’s value must define a duration that is longer than the time it takes the Mirata Forms-enabled MDK mobile application to complete any one of its data synchronization (or “sync”) sessions.

2.4 Execute the Cloud Foundry CLI Installation Command Script for FOIL

The Mirata FOIL software directory contains a file with an installation script that executes Cloud Foundry (CF) CLI commands to build the following components and deploy them to the designated SAP BTP subaccount space…

Perform the following steps to execute the FOIL installation command script:

Authenticated access to the selected BTP subaccount space via the CF CLI will remain valid for a 24-hour period, during which time execution of the cf login command will not be required prior to executing additional CF CLI commands. However, if you need to access a different BTP API endpoint, subaccount and/or space within this period, the CF CLI cf login command must be executed again using the -a command line option.

2.5 Provide FOIL XSUAA Configuration Data to Mirata

Once the FOIL application has been configured and installed in your SAP BTP subaccount space, a "trust relationship" must be established between the Mirata identity provider (IdP) and the FOIL XSUAA service (and by extension, to the default IdP configured in the BTP subaccount). To establish this trust relationship, configuration data from the FOIL XSUAA service instance must be obtained and provided to Mirata Support as follows:

3.1.1 Obtaining the Mobile Destination Endpoint URL for FOIL

Every Mobile Destination definition requires an endpoint URL. For FOIL, this URL is the Application Route assigned by BTP, which is obtained as follows:

1. Navigate to the home page of the BTP subaccount space that hosts the FOIL application
2. Select the Applications (vertical) tab
3. In the Applications table, in the Name column, select the forms-odata-interface-layer hyperlink
4. On the resulting page, the URL is listed in the Application Routes section

3.1.2 Add a Mirata Mobile Destination in Mobile Services 

To add a Mirata Mobile Destination to a Mirata Forms-enabled MDK mobile application hosted by BTP Mobile Services, perform the following steps:

1. Navigate to the BTP subaccount space that is hosting the FOIL application instance
2. Expand the Services (vertical) tab
3. Select the Instances (vertical) tab
4. In the Service Instances table, identify the row for the Mobile Services instance that is hosting the Mirata Forms-enabled MDK mobile application, select the instance name (which is a hyperlink) and authenticate with Mobile Services (if required).
5. On the resulting Mobile Services page, in the Assigned Features table, select the Mobile Connectivity item
6. On the resulting Mobile Services page, select the "Create" toolbar icon (i.e.- the sheet of paper with an overlaying asterisk)
7. On the 1. Basic Info page of the Create Destination data entry wizard, enter the following data:

8. Press Next
9. On the 2. Custom Headers page, Press Next
10. On the 3. Annotations page, Press Next
11. On the 4. Destination Configuration page, enter the following data:

12. Press Next
13. On the 5. SSO Mechanism page, Press Finish
    

3.1.3 Updating the XSUAA Setting of a Mirata Forms-enabled MDK Mobile Application Instance 

Each instance of a Mirata Forms-enabled MDK mobile application published to Mobile Services must be configured to use the XSUAA service instance installed with FOIL, as follows:

1. Navigate to the BTP subaccount space that is hosting the FOIL application instance
2. Expand the Services (vertical) tab
3. Select the Instances (vertical) tab
4. In the Service Instances table, identify the row for the Mobile Services instance that is hosting the Mirata Forms-enabled MDK mobile application, select the instance name (which is a hyperlink) and authenticate with Mobile Services (if required).
5. On the resulting Mobile Services page, select the Security (horizontal) tab
6. Scroll down to the XSUAA Settings section and select the section’s edit toolbar icon (i.e.- the pencil)
7. In the resulting dialog window, select the forms-xsuaa item in the XSUAA Service dropdown field
8. Select OK to dismiss the Edit XSUAA Settings dialog window
9. Select OK to dismiss the Confirm Save dialog window

3.2 Testing a Mirata Mobile Destination in Mobile Services

3.2.1 Prerequisites

Note: The MDK mobile application used for to perform this connectivity test does not need to be a Mirata Forms-enabled mobile application. The Mirata Mobile Destination may be temporarily added to any functional MDK mobile application instance for the purpose of performing the test outlined in the section below.

3.2.2 Test the Mirata Mobile Destination Using the OData Application Destination Test Tool

1. Navigate to the BTP subaccount space that is hosting the FOIL application instance
2. Expand the Services (vertical) tab
3. Select the Instances (vertical) tab
4. In the Service Instances table, identify the row of the Mobile Services instance that is configured with the Mirata Mobile Destination, select the instance name (which is a hyperlink) and authenticate with Mobile Services (if required).
5. On the resulting Mobile Services page, in the Assigned Features table, select the Mobile Connectivity item
6. On the resulting Mobile Services page, in the Mobile Destinations table, identify the table row with the Name column value of MIRATA_ODATA_API. In the Actions column of this row, select the OData Application Destination Test toolbar icon (i.e.- the sheet of paper with an overlaying magnifying glass)
7. On the resulting screen (which may take several seconds to appear), in the Metadata Entity Set dropdown field, select the UserInfo list item
8. Verify that a single row of entity set result data appears in the Entity Data section

Note: Data may or may not be returned for the other entries of the Entity Set dropdown field based on the data that currently exists in the Mirata environment

4 Maintaining the FOIL BTP Application

4.1 Maintaining the FOIL XSUAA Service’s Configuration

When modifications are made to the forms-xsuaa.xs-security.json configuration file, the FOIL XSUAA service can be updated accordingly by executing the following CF CLI command…

cf update-service forms-xsuaa -c forms-xsuaa.xs-security.json

The command above assumes that the formsxsuaa.xssecurity.json XSUAA configuration file exists in the current working directory. If this is not the case, either a relative path, or the fully qualified path, to the forms-xsuaa.xs-security.json configuration file must be specified.

4.2 Maintaining the FOIL Destination Service’s Configuration

4.2.1 Maintaining FOIL Destination Service Definitions

If your organization has multiple Mirata environments (e.g.- development, quality assurance and production), each Mirata environment will have a unique API endpoint. The FOIL application utilizes a BTP Destination Service instance (named forms-destination) to define and manage the connection criteria of each Mirata API endpoint. A destination definition for each existing Mirata environment will be established when FOIL is installed.  

Individual destination definitions can be maintained using the BTP web-based user interface, as follows:

1. Navigate to the BTP subaccount space that hosts the FOIL application
2. Expand the Services (vertical) tab
3. Select the Instances (vertical) tab
4. In the Service Instances table, select the forms-destination hyperlink in the Instances column
5. On the resulting screen, select the Destinations (vertical) tab

4.2.2 Configuring the Active FOIL Destination

The specific Destination Service definition that FOIL utilizes to connect to a Mirata API endpoint is specified using a User-Provided Variable, the value of which is managed as follows:

1. Execute steps 1 through 5 in section 4.2.1 above to view the existing Mirata API endpoint destination definitions
2. Record the value in the Name column of the row in the Destinations table that defines the target Mirata API endpoint
3. Navigate to the BTP subaccount space that hosts the FOIL application
4. Select the Applications (vertical) tab
5. In the Applications table, in the Name column, select the forms-odata-interface-layer hyperlink
6. On the resulting page, select the User-Provided Variables (vertical) tab
7. In the User-Provided Variables table, select the edit (i.e.- the pencil) icon in the Actions column of the table row with the Key column value odata_destination
8. In the resulting Modify User-Provided Variable dialog, in the Value field, enter the name of the Mirata API endpoint destination obtained in step 1 above and select Save
9. Repeat steps 3 through 5 above
10. On the resulting page, select the Restart button (near the top of the screen) to restart the FOIL application

4.3 Updating the FOIL Application

Updates to the FOIL application will be periodically issued by Mirata. Neither the FOIL XSUAA service nor the FOIL Destination service will be modified by applying a FOIL update.  

4.3.1 Preparing the FOIL Update Software

The FOIL update software is provided in a Zip archive file (foil.zip). Expand this archive file into an empty file system directory. 

Note: In the following section, this directory is referred to as the “Mirata FOIL software directory”

4.3.2 Execute the Cloud Foundry CLI Update Command Script for FOIL

The directory the FOIL update archive was expanded into contains a file with an update script that executes Cloud Foundry (CF) CLI commands to build and deploy the updated FOIL application to the designated SAP BTP subaccount space.  Perform the following steps to execute the FOIL update command script:

Authenticated access to the selected BTP subaccount space via the CF CLI will remain valid for a 24-hour period, during which time execution of the cf login command will not be required prior to executing additional CF CLI commands. However, if you need to access a different BTP API endpoint, subaccount and/or space within this period, the CF CLI cf login command must be executed again using the -a command line option.

5 Appendix A: Acronyms, Abbreviations & Definitions