Modules Distribution in GeneXus

GeneXus allows distribution of the API and binaries of a Module and installation of it in other Knowledge Bases. 

A Module installed using this mechanism, provided by another KB, has the following characteristics:

• Just the API of the module is visible
• The API is read-only
• It consists of a specific version of the API and also its implementation (the corresponding binaries in possibly several platforms or languages)

That provides the following benefits:

• It allows preserving the privacy of the code
• It is very clear that the module is maintained by the provider, under a certain license, and unwanted changes are avoided.
• It improves build performance (Code is built just once, in the origin)
• Modules can be easily distributed in the company or publicly through a repository manager  

GeneXus itself uses this mechanism to provide the GeneXus Core module and others, like GeneXus Cognitive API. 

Understanding the modules lifecycle, step by step

Through the following steps, you can create a module, distribute it, install it in another KB, and use it there.

1) Create a module with a specific functionality

First, you create a module with specific functionality and test it thoroughly in the platforms you want to provide it.

For this, read HowTo: Create a Module Object, HowTo: Add an object to a Module, and Modules - Defining an interface.

2) Package and Publish a module

Then, you package and publish the module, adding a description of the functionality, link to documentation, and other relevant information.

For this, read Package and Publish Modules.

Now, you are done: You shared your module on a Modules Server.

3) Create or open another KB, and install the module

Open the Manage Module References tool window and install it.

4) Now you are ready to use it. 

Note: The binaries of the referenced modules will be copied to your target environment directory during build time.

 

Objects that are packaged

This is a list of objects that could belong to the module's API and implementation. 

• Services
  • Data Provider object
  • Procedure object 
  • External Object
• Data
  • Domain object
  • Structured Data Type (SDT) object 
• Structure
  • Folder object
  • Module object
• User Interface (Design System)
  • Design System Object
  • Stencil object
  • Image object
  • File object
  • User Control object

Note: Implementation of Business Components referenced by the implementation of the module's API is also packaged.

Considerations

The REST service and the corresponding implementation resulting from Procedures that have the REST Protocol property set as True are packaged even when those Procedures are not public (Object Visibility property set as 'Internal', 'Private' or 'Knowledge Base'). This allows packaging REST services to be deployed wherever the module is used.

Sample

There is a KB with the following structure:

Root Module
|_ MyModule
   |_ ProcedureA (inherit)
   |_ InternalModule
       |_ ProcedureB (internal, online, REsT)

And these details:

• ProcedureA calls ProcedureB.
• The Object Visibility property is set for ProcedureA as Public (exposed) and for ProcedureB as Intenal/Private (not exposed).
• The Connectivity Support property  is set for ProcedureA as inherit, and for ProcedureB as online. 
• ProcedureB has the properties Expose as Web Service and REST Protocol set as True.

When installing MyModule on another KB, if an offline Panel (Connectivity Support = Offline) for Native Mobile (Apple, Android) calls MyModule.ProcedureA, it is executed on the device (that is, offline) and it is able to call the service layer of the same app via REST. 

MSBuild Tasks for Continuous Integration

There are several MSBuild tasks that help automate tasks or installation, publishing, etc. : More information at Modules MSBuild Tasks

General Restrictions

• When Packaging
  • Only submodules of the Root Module can be packaged (i.e. A module with a parent that is not the Root cannot be packaged)
  • Circular dependencies between modules are not allowed
  • Business Components must not be referenced in the module interface's Parm rule or Output property
  • Translation type property must be set to 'No Translation' (default)
  • If you package a module with database access, read: Package Module with database access for Solutions extensibility scenarios 
• On the Target KB
  • The distributed module must be generated with the same GeneXus version as the one that references the module.
  • Downgrade (installing a lower version of an already installed module) is not fully supported. 

FAQ

Q: What if the following situation happens: In KB "Provider" is Object A and that object is exported to KB "Client". Then, in KB "Provider", Object A is put into a module M and then that Module is packaged and installed in KB "Client"? 
A: Since the internal GUID of object A remains unchanged, GeneXus resolves all; that means: References to object A will now point to M.A. A is not anymore in its folder, it is in the module M under References in KB Explorer; it is read-only and only its interface is available.

Q: Not every Procedure in my module got packaged. What happened?
A: In order to be packaged, your objects in the module must be in some main object call tree. So if you have unreachable objects, these will not be packaged. Make sure you add the needed objects to some main object call tree. It could be just a dummy Procedure outside of your Module just for that purpose.