PredixMobilityConfiguration

The PredixMobilityConfiguration class contains configuration interfaces and methods to allow PredixGoSDK consuming apps to customize various aspects of SDK functionality

Methods:

loadConfiguration()

called to load the SDK's initial configuration. Since this sets default logging levels, ideally this is called as early as possible in the app startup process. If it is not called by the time the PredixMobilityManager.startApp() method is called, it will be called at that time.

---

appendDataViewDefinition(viewName: String, version: String, mapFunction:(properties: [String : AnyObject], emit: (AnyObject, AnyObject?)->())->(), reduceFunction: ((keys: [AnyObject], values: [AnyObject], re: Bool) -> (AnyObject))?)

appendDataViewDefinition(viewName: String, version: String, mapFunction:(properties: [String : AnyObject], emit: (AnyObject, AnyObject?)->())->())

appendDataViewDefinition(viewDefinition: ViewDefinition)

Used to create data views for querying data documents within the application.

• viewName: Name of the view. If the name contains a "/" character, the view can be queried through the CDB service. The view name "foo/bar" would be queried with a CDB service query like:

  http://pmapi/cdb/~/_design/foo/_view/bar

• version: Version number of the view. Must be changed if the code within the mapFunction or reduceFunction changes.

• mapFunction: closure that defines the view, and will be called during indexing. The properties parameter will include the data document. For every call to the emit function, an indexed key (first parameter) and value (second parameter) will be created. Keys can then be used to filter (query) the view. In addition to primitive types, both keys and values can also be arrays. Arrays as values are very useful is can allow multiple values to be returned when querying the view, preventing the need to retrieve an entire document when only a few values are needed.

• reduceFunction: closure that, if included, is run against the data returned from the view query. This closure can then be used to further massage the data before returning it to the caller.

MapReduce is a common pattern.

Examples:

    PredixMobilityConfiguration.appendDataViewDefinition("myviews/documents_by_type", version: "1", mapFunction: { (properties, emit) -> () in
        if let type = properties["type"] as? String
        {
            let isDeleted : Bool = properties["_deleted"] as? Bool ?? false
            if !isDeleted
            {
                emit(type, nil)
            }
        }
    })

Then a subsequent query:

http://pmapi/cdb/~/_design/myviews/_view/documents_by_type?key=%22test%22

would return all documents that contained a "type" field, that were not flagged for deletion, where the value of the "type" field was "test". The returned rows would contain only the id, and type field, no additional values.

Using Map/Reduce to return draft documents when they exist

Consider this scenario, you have a document to update, but the update may fail due to backend approval rules or processes. This approval may take time, and during this process you want the user that made the change to see the updated data, but other users should not. Using the CQRS pattern, and Map/Reduce in a few views, is one way to acheive this:

First, to update a document, using CQRS pattern, you're going to create a seperate command document. This will be the message to a backend command processor to validate and perform the update. Secondly, create a draft document, which will be a copy of the original document, and the changes being requested in the command. This draft document should have the same _id as the original document, plus a suffix to identify it as a draft, like "_DRAFT". Extrapolating this pattern further, you could make additional updates to the same document, by further appending the draft suffix, and creating additional command documents. These draft documents should be assigned a channel private to the user, so while the documents will replicate to the server, they will not be distributed to any other users.

So, using this pattern, you will have data that looks like this:

    {"_id": "doc_fruit", "data": "apple", "channel" : "everyone"},
    {"_id": "doc_fruit_DRAFT", "data": "orange", "channel" : "user"},
    {"_id": "doc_fruit_DRAFT_DRAFT", "data": "banana", "channel" : "user"},
    {"_id": "doc_furniture", "data": "chair", "channel" : "everyone"},
    {"_id": "doc_furniture_DRAFT", "data": "table", "channel" : "user"},
    {"_id": "doc_color", "data": "blue", "channel" : "everyone"}

Let's assume our UI needs to display our _id field, and the data field:

ID              Data
-------------   --------
doc_fruit       banana
doc_furiture    table
doc_color       blue

A view with a map/reduce defined like this can acheive this:

    PredixMobilityConfiguration.appendDataViewDefinition("views/get_id", version: "1.0", 
      mapFunction: { (properties, emit) in
    	  // This emit gives us keys of the "_id" field, and values of the "data" field
          emit(properties["_id"]!, properties["data"]) 
      }
      reduceFunction: { (keys, values, re) -> (AnyObject) in

          // our return data is a an array of dictionaries
          var returnData : [[String : String]] = []

          // keys and values are parallel arrays, containing data from above emit
          // convert these from AnyObject arrays to String arrays to allow easier processing below
          if let stringKeys = keys as? [String], dictValues = values as? [String]
          {
              var ndx = 0
              //loop through the arrays, identifying the first and last documents with matching ids
              while ndx < stringKeys.count
              {
                  var skip = ndx
                  while skip < stringKeys.count - 1 && stringKeys[skip].stringByAppendingString(DraftIdSuffix) == stringKeys[skip + 1]
                  {
                      skip += 1
                  }

                  //create a dictionary with the original id, and the last draft data
                  let dic : [String : String] = ["id" : stringKeys[ndx], "data" : dictValues[skip]]
                  returnData.append(dic)
                  ndx = skip + 1
              }
          }
          return returnData 
    })

This query definition will result in a returned JSON object like:

    {
      "offset": 0,
      "rows": [
        {
          "key": null,
          "value": [
            {
              "id": "doc_color",
              "data": "blue"
            },
            {
              "id": "doc_fruit",
              "data": "banana"
            },
            {
              "id": "doc_furniture",
              "data": "table"
            }
          ]
        }
      ],
      "total_rows": 6
    }

We can see here that our original document ids are associated with the latest draft data. No special handling is needed when data does not have a draft, and this type of map/reduce pattern can be very efficient.

A similar technique could be used to return just the id of the deepest level draft document or other manipulations.

Full Text Search views:

A view can be setup to allow for full text searching in string fields. The class FullTextSearch has a static function, createKey. If the output of this function is used as the first parameter of the emit function, the resulting view will be a full-text search view.

Example:

    PredixMobilityConfiguration.appendDataViewDefinition("myviews/search_large_text", version: "1", mapFunction: { (properties, emit) -> () in
        if let largeText = properties["largeText"] as? String
        {
      	   let textKey = FullTextSearch.createKey(largeText)
           emit(textKey, nil)
        }
    })

Querying a full-text view can then be done using the CDB service:

http://pmapi/cdb/~/_design/myviews/_view/search_large_text?full_text=%22searchterm%22

In addition to the querystring parameter full_text, the parameter "snippets" can be included. If this is included, each row in the resulting return set will include a "snippet" property containing a snippet of the full text highlighting the matched search words.

http://pmapi/cdb/~/_design/myviews/_view/search_large_text?full_text=%22searchterm%22&snippets

The full_text parameter can include:

• Either individual words, or phrases delimited by double-quotes.
• Appending a * to a search term denotes a prefix search that matches any word beginning with that term.
• When multiple search terms are separated by spaces, all of them have to match -- it's an implicit "AND" conjunction.
• You can also put the words AND or OR (in all caps) between terms.
• The word NOT (in all caps) before a term negates it: only rows that don't include it will be returned.
• The word NEAR (in all caps) between terms is like AND but also requires that the matches be near each other.
• NEAR can be followed by a "/" and a number to indicate how near one term must be from another to be a match: NEAR/3 would indicate the search terms must be within three words of each other. Default NEAR alone is equivalent to NEAR/10.
• Multiple terms or expressions can be wrapped in parentheses for grouping.

Properties:

• automaticallyListenForApplicationStateEvents

By default the SDK will automatically listen for these application state events:

• applicationWillResignActive
• applicationDidEnterBackground
• applicationWillEnterForeground
• applicationDidBecomeActive
• applicationWillTerminate

Setting this property to false will prevent this, in which case the container app is expected to call these methods on the SDK directly. If this property is true, but the SDK method for a state event is called by the container anyway, the SDK will stop listening to that particular event, and expect the container app to continue to call the method directly.

• considerUIReadyWhenApplicationDidBecomeActive

The SDK needs to know when the UI is ready to start the interaction and to display elements on the screen. By default, the SDK knows the UI is ready when the SDK's applicationDidBecomeActive method is called. This behavior can be overridden by setting this property to false. In which case the SDK will wait until it receives a posted UIReadyNotification notification before considering the UI to be ready to start interaction.

• defaultLoggingLevel

sets a default logging level for logging within the system.

• defaultDatabaseName

sets the default local database name.

• authenticationScheme

sets the scheme component of the authentication grant redirect used by oAuth authentication

• authenticationGrantIndicator

sets the hostname component of the authentication grant redirect used by oAuth authentication

• loggingLevelConfigKey

sets the key used to load the logging level setting from iOS Settings or Info.plist

• loggingLevelConfigLocation

sets where the logging level configuration is located, iOS Settings or Info.plist

• serverEndpointConfigKey

sets the key used to load the server endpoint setting from iOS Settings or Info.plist

• serverEndpointConfigLocation

sets where the server endpoint configuration is located, iOS Settings or Info.plist

• traceLogsRequestsConfigKey

sets the key used to load the "trace logs all requests" setting from iOS Settings or Info.plist

• traceLogsRequestsConfigLocation

sets where the "trace logs all requests" setting configuration is located, iOS Setting or Info.plist

• userSessionURLPath

sets the URL path used obtain user information during online authentication

• loginURLPath

sets the URL path used to login during online authentication

• logoutURLPath

sets the URL path used to logout online

• dataReplicationURLPath

sets the URL path used to replicate the local database while online

• authorizationCheckURLPath

sets the URL path used validate authentication

• authorizationCheckAuthorizedStatusCode

sets the status code used to verify valid authentication

• authorizationCheckValidStatusCodes

sets the status codes used to verify authentication valid or invalid. If an authorization check returns a status code not in this list, it's considered the authentication server cannot be reached and the local system is no online, but may still have internet access.

• userSessionUsernameKey

sets key used during the userSessionURLPath call to obtain the name of the user

• userSessionAuthenticatedKey

sets key used during the userSessionURLPath call to obtain the validation state of the user

• userSessionDatabaseNameKey

sets key used during the userSessionURLPath call to obtain the local database name

• pmappDocumentNameKey

sets the key used to find the pm app document name

• pmappDocumentNameConfigLocation

sets where the pmappDocumentNameKey configuration is located, iOS Settings or Info.plist

• pmappDocumentVersionKey

sets the key used to find the pm app document version

• pmappDocumentVersionConfigLocation

sets where the pmappDocumentVersionKey configuration is located, iOS Settings or Info.plist

• pmAppDocumentWebAppNameKey

sets the key used to find the initial web app name in the pm app document

• pmAppDocumentOfflineAppNameKey

sets the key used to find the offline login app name in the pm app document

• pmAppDocumentDependenciesKey

sets the key used to find the web app dependancies list in the pm app document

• API_HOST

sets the hostname used for internal service calls within the app

• seriousErrorDefaultMessage

sets the default text to display when the app encounters an unresolvable error

• seriousErrorPage

sets the bundled HTML page used to present unresolvable errors to the user

• additionalBootRestartWorkflow

sets an optional closure which, if set, will be called during the boot restart workflow.

• additionalBootServicesToRegister

An optional array of services that, if set, will be integrated into the boot service services registration/unregistration process.

• shouldLogUnhandledErrors

sets whether or not the SDK will log unhandled errors

• shouldInitializeDefaultsFromSettings

sets whether or not the SDK will load default iOS Settings values from the Settings bundle

• shouldIssueWarningsForPlaceholderULRs

sets whether or not the SDK will log warning messages when images from "placehold.it" are detected

• requireDevicePasscodeSet

sets whether or not the boot service will return an error if the device does not have a passcode set.
Defaults to true. iOS device passcodes are a critical security feature, and it's recommended for a secure system a passcode should be required.

• localStorageURL

The file URL where all data used by the SDK is stored.

• userLocalStorageURL

The file URL for data specific to the logged in user

• keychainAccessGroup

If set, all keychain access will use this Keychain access group

• keychainKeyPrefix

A prefix used for all Keychain items. Defaults to the application's bundle id.

• versionInfo

String of version information for SDK and dependent libraries

• defaultInitializationDetectionKey

sets the key used to detect changes in iOS Settings and automatically load them

• traceLogsAllRequestsDefault

sets whether or not the SDK will by default log all HTTP requests detected within the app when logging is in Trace mode.

• dataViewDefinitions

An array of view definitions, consisting of a view name, version, and closure that maps the view. The method appendDataViewDefinition(...) is a helper method to append new definitions to this array.

• displaySeriousErrorPopup

A closure with the definition: (errorMessage: String, onRetry: () -> ())->() This closure allows the implementation of the non-web based serious error pages to be overridden. In iOS the default implemenation shows a UIAlertController with the error details. In the macOS version of the SDK there is no default implmentation. MacOS containers must include a web-based serious error page, or should implement this closure.