App Package Guide
Table of Contents
Action App Package (hereinafter referred to as App Package) is a mechanism for managing and distributing Gravio actions, triggers, and related resources as a single package. It aims to efficiently develop action flows and easily deploy them to other Hub systems.
1.1 Evolution from Traditional System (Feature Package)
The development of App Package went through several stages:
- Achieving portability
- Including all necessary files for trigger and action execution within the app
- Design that works when transplanted to different Hub environments
1.2 Benefits of App Package
App Package offers the following benefits:
- Improved Portability: The entire package can be moved to other Hubs and operated without additional configuration
- Access Control: Resources within the package are isolated from external access, maintaining an organized state
- Easy Distribution: Can be deployed to other Hubs without file changes, making distribution simple
- Namespace Separation: Each resource within the package has a namespace separated from the global environment
2. Structure of Action App Package
2.1 Basic Directory Structure
App Package is implemented with the following directory structure:
actmgr/actions/
+- [appname].app/
+- actions/ # Action files
| +- a.acs
| +- b.acs
+- data/ # Resource files
| +- sounds/
| +- a.mp3
+- triggers/ # Trigger settings
| +- events/
| | +- xxx.json
| +- timers/
| +- calendars/
+- bases/ # Base properties
| +- xxx.basp
+- layers/ # Layer information (under development)
2.2 Role of Each Directory
- actions/: Stores action files (.acs) within the App Package
- data/: Stores various resource files referenced by actions
- triggers/: Stores settings for event triggers, timer triggers, calendar triggers, etc.
- bases/: Stores base properties used by components
- layers/: Stores layer-related information (※currently under development)
3. Steps to Create Action App Package
3.1 Basic Creation Flow
The basic steps to create a new App Package are as follows:
- Create a directory with extension
.app in the actmgr/actions directory
- Create necessary subdirectory structure:
actions/data/triggers/events/triggers/timers/triggers/calendars/bases/layers/ (※future support)
- Place existing actions and resource files in appropriate directories
- Execute reload in Trigger Manager to enable the package
3.2 File Placement Rules
File placement follows these rules:
- Action Files:
.acs files are placed in the actions/ directory
- Trigger Files: Various trigger files are placed in appropriate subdirectories under
triggers/
- Base Properties: Used base properties are placed in the
bases/ directory
- Resource Files: Files referenced by components are placed in appropriate directories under
data/
The important point is that files work by simply copying them without changing their content. IDs are separated from the global environment, so there are no ID duplication issues.
4. Package Reference Control
4.1 Action References within App
Triggers and actions within App Package generally only reference resources within the same package:
- When specifying action IDs in triggers, only actions within the same App are referenced
- When specifying other actions in Call/Jump components, only the same App is searched
- Base property references prioritize those within the same App
- File references are resolved based on the App’s
data/ directory
4.2 Relationship with Global Actions
The relationship between global environment and App Package is as follows:
- To execute actions within App Package from global triggers, specify in
appname/actionid format
- Actions triggered by triggers within App are only those within the App (global actions with the same ID are not triggered)
- Internally, action IDs within App are converted to
appname/actionid format for processing
5. Distribution Methods to Other Hubs
5.1 Package Export
Steps to distribute App Package to other Hubs:
- Archive the entire
.app directory
- Transfer the archive file to the destination Hub
- Extract to the
actmgr/actions/ directory on the destination Hub
- Execute Trigger Manager’s reload function to enable the package
5.2 Distribution Notes
- No file content changes are needed (works as is)
- When the same trigger conditions are met on the destination Hub, the package’s actions are executed
- Layer information transplantation is not fully supported at this time
6. Known Limitations and Incompatibility Points
App Package has the following limitations and incompatibility points:
- File Reference Relative Paths: When using
.. etc. to reference outside the data directory, reference destinations differ between global actions and App actions
- Base Property Fixation: Since base properties are also packaged, environment-specific settings (such as SMTP server) become fixed
- Security Concerns: Although encrypted, passwords and other information need to be included in the package for distribution
7. Future Improvement Directions
7.1 Base Property Handling Improvements
The following improvements are being considered for base properties:
- Allow users to specify base property IDs
- Enable prioritizing global base properties over those within App
- Provide option to package only reference information without base properties
This will improve flexibility to operate with settings appropriate for the destination environment.
7.2 Global/App Integration Enhancement
Future improvements will focus on strengthening integration between global and App environments:
- Enhanced cross-package communication
- Improved resource sharing mechanisms
- Better security controls for cross-package operations