Skip to end of metadata
Go to start of metadata

Beyond system-wide configuration data, the most common data used by modules is project-based resource data. The project management system in Ignition provides a variety of facilities to help modules store and retrieve data. The actual information stored is opaque binary data, allowing the module to use any scheme that is appropriate.
Project resources are usually created through the designer, so this section will focus on how the gateway accesses and uses the resources. More information about projects and project resources can be found in the Design Concepts section and in the Designer chapter.

Identifying Project Resources

Project resources are identified by their resource type, module id, and scope. Additionally, each resource has a numeric id, and a universally unique id. When a module defines a new project resource, it will define the resource type, which is a free-form string. It will also define the scope of the resource. Resources scoped to the gateway, for example, will not be sent to clients. The project management system makes it easy to retrieve resources for a given module or of a given type, for the specified scope.

Loading Project Resources

Modules in the gateway can retrieve resources through the ProjectManager provided by the GatewayContext. The first step is to retrieve the Project, and then from there retrieve the resources, based on type, module, or other parameters. After retrieving the resource, the data can be extracted and deserialized.

Retrieving Projects

It's important to realize that the Project class serves a variety of purposes. It can be a fully loaded project, but can also represent a subset of a project, or simply the structure, without resource data actually present. Therefore, the first step in loading data is to make sure that you are using the correct project object.

Often modules will start by calling ProjectManager.getProjectsFull(). This will return a list of all projects, fully loaded. Since Ignition supports any number of projects, it's important that modules are designed to handle them as well. It is usually advisable to define a "project runner" object that runs each project in a sandbox, as interaction between projects is rarely expected. If the id or name of the project is known, it can be retrieved directly with the ProjectManager.getProject() functions.

When retrieving projects, a ProjectVersion is specified.  Each project potentially exists in two states- Staging, and Published.  Many times there is little difference, as projects are set to "auto-publish" by default.  However, it is important to make a distinction early on between these two versions, and decide how your module should treat them. If you want to update the running state each time a change is made and the project saved, load the Staging version. If you only want to update the state when the user "publishes" the project, only load the Published version. Since project resources always go to staging first, if the action of publishing doesn't mean anything to your module, it is not necessary to load both versions.

Loading Resources

Once a project is retrieved, resources can be retrieved through several functions on the Project object. Most commonly, modules will want to load specific types of resources at a time, which can be accomplished with the Project.getResourcesOfType() function.

Deserializing Resource Data

Once the project resource is retrieved, the data can be accessed through ProjectResource. getData(). If the data was serialized through Ignition's XML serialization mechanism, the full code to deserialize a resource object might look like:

MyModuleResource obj = (MyModuleResource) XMLDeserializer.deserialize (gatewayContext.createDeserializer(), resource.getData(), log);

Important: When deserializing, it is important to use the deserializer created by GatewayContext.createDeserializer(). Do not create your own XMLDeserializer.

Listening for Project Changes

Modules can add a ProjectListener to the ProjectManager in order to be notified when a project is added, removed, or modified.  It is important to remember that the listener will be notified for all projects, and that the Project object provided will only be the difference between the last project state and the new one. If the full project is required, for example to resolve full folder paths of resources, you should retrieve it from the ProjectManager using the id provided by the supplied project.

  • No labels