Note: The following information is intended for developers and advanced users with expertise in integrating APIs and protocols.  


Through Connectors, Miracle Mobile Forms enables the easy integration of mobile forms with an organization’s ERP systems, databases, CMS, and other kinds of business data systems. While there are numerous configurable connectors, including MsSQL connector, custom connectors which leverage the platform's connector API can also be created by developers and advanced users.


The following lines will explain Custom Connectors in Miracle Mobile Forms and how to create them.  

 

Common Functions and Properties of Miracle Mobile Connectors

Miracle Mobile Forms supports two types of connectors:

  1. Authentication Connectors – This type of connector enables users to log in to a system such as a Line of Business (LOB) system, a directory server, or both.
  2. Data Connectors – This type of connector supports the creation, querying, and update of data. It can also work with an authentication connector.


Both types of connectors share common properties and functions. These are listed below.

 

DisplayName Property

This property returns the display name of the connector, which is what the user sees on the Connections page in Miracle Studio.

 

Icon Property

This property returns the icon of the connector or LOB system. 


The value of this property is shown as a Data URI, which comprises four parts: a prefix ( data: ), a MIME type indicating the type of data, an optional base64 token if non-textual, and the data itself. For instance, data:image/gif;base64 can be used for the base64 encoded data of a PNG image.

 

GetConnectionParameters Function

This function acts as a blueprint for the parameters which this connector requires to connect to a third party system. For example, a database connector would require the parameters hostname, port, username, password, and database name.

 

GetContext Function

This function can be considered as the first step in a connector’s usage lifecycle as it is called before invoking any service methods. The value returned by this function will be passed as a parameter to every subsequent servicing method call.


GetEntities Function

This function returns all the entities which this connector needs to expose. An entity is a logical data structure with a few properties. It is supposed to expose data objects from the underlying server. An entity also specifies the structure in which data exchange may happen between the connector and Miracle Mobile Forms. For example, a database server may expose each table in the underlying database as an entity. Each column within a table would then be exposed as a property of that entity.


This function is optional when implementing an Authentication connector. By default, authentication connector classes implement this method for login-related entities. However, connectors that require more than the login functionality will need to override this function and add their own entities to the list.


For authentication connectors, entities can be used to describe the parameters for functions like Login, Registration, and ChangePassword.

 

SupportsIncommingHTTP Property

This property indicates whether a connector can and wants to expose a URL as well as handle incoming HTTP requests targeted specifically for the connector.

(Note: This functionality is not fully available at the time of this document’s release, and it is not utilized as of now. However, it may be available in the future for specific use-cases.)

 

HandleIncommingHttpRequest Property

This is the core function which will be called upon receiving an incoming HTTP request that a connector should handle.

(Note: This functionality is not fully available at the time of this document’s release, and it is not utilized as of now. However, it may be available in the future for specific use-cases.)



 

Custom Connectors Guide.docx

Diagram: Lifecycle of a Connector

 

 

Features of Authentication Connectors

Authentication connectors perform a number of basic login and user session-related functions. They can be categorized into two kinds of connectors: 

  1. Plain Authentication Connectors
  2. Authentication Connectors.


As its name suggests, a Plain Authentication Connector is a simpler version of the fully functional Authentication Connector. It can be considered as an adapter that is written on top of the regular Authentication Connector class to simplify the most common implementation approach, i.e. the login functionality.


The features an authentication connector can support are listed below.

 

LoginUser Function

This function takes a dictionary of login credentials as input and returns a LoginContract to indicate that the login was successful. This LoginContract acts as a token supplied by the platform to identify the user who was authenticated. It can be used in subsequent calls to other connector functions.

 

UserHasRole Function

This function validates if a provided user has a specified role assigned or not.

 

VerifyLogin Function

This function confirms whether or not a LoginContract object is still valid.

 

GetContractCodec function

This function returns an object of the class LoginContractCodec. It is used to serialize or deserialize a login contract object. This mechanism is important for the platform to function since login contracts need to be serialized and stored as strings in the platform’s persistent storage. 


The LoginContractCodec should be able to serialize the LoginContract object as a string and reconstruct the same object from the string representation that it returned earlier.

 

Note: Some functions are no longer used because they have been replaced by other functions or are not needed anymoreThe following functions may be removed in a later version of the server side release:

  • GetAuthenticationParameters

 

Features of Data Connectors

Data connectors mainly deal with services and data exposed by third party servers. These connectors expose a variety of functions that perform business functions specific to an LOB system or third party service.


The features a data connector can support are listed below.

 

SupportsEntityGeneration Property

This property indicates whether or not a connector supports the entity generation functions, GenerateEntitiesPreview and GenerateEntities.

 

GenerateEntitiesPreview function

This function generates a preview of the underlying data structures that will be created on the underlying LOB or third party service upon calling the GenerateEntities function.

 

GenerateEntities Function

This function allows the generation of underlying data structures based on the Entity definitions it deems necessary for the application’s functionality.

 

GetNotificationDefinitions Function

This function exposes any notification definitions that it deems necessary to Miracle Mobile Forms.

 

GetNotifications Function

This function is supposed to return any notifications (instances) that need to occur immediately based on a notification definition retrieved earlier by the GetNotificationDefinitions function.




Need more help? Contact us at support@miraclemobile.com.au.