Upload, Update, Use (Git)
Instead of you uploading modules to ApiOmat directly, you only have to push code changes to the Git repository and trigger that ApiOmat pulls the changes from the repository.
The following three cases exist:
-
You change code
-
You change the data model (e.g. add a MetaModel, change attributes of a MetaModel, ...) via dashboard or REST API
-
You change code and at the same time the data model gets changed via dashboard or REST API
In all cases we will refer to the "MyModules/Native Modules" page (e.g. http://apiomat.yourcompany.com/dashboard/myModule/index), which will look similar to the following after you've created a Native Module:
1. You change code
You can make changes to the code you checked out locally to your computer via Git. Either you add/remove/change attributes to a MetaModel, add/remove a whole MetaModel or implement hook methods.
After you've done that, you just commit and push the changes to the Git repository. Then you send a request to the URL that triggers a pull and deploy (see screenshot at the beginning of this page). You can do this by simply clicking on the link in the dashboard or you can automate it by using git hooks in your Git repository. You can also create git hooks which trigger the call of this URL automatically when there are code changes pushed to the repository. For further information about this automation see Git Automatic pull trigger integration.
The response should be similar to the following: "Checked out and deployed module NewNM, system LIVE".
You can also trigger this in the Apidocs or via cURL with a request to the endpoint: /modules/{moduleName}/git. See https://apiomat.yourcompany.com/apidocs/index.html#!/modules/cloneAndDeployNativeModuleGit. It's the same URL as shown in the dashboard (or in the screenshot at the beginning of this page).
2. You change the data model via dashboard or REST API
You can change the data model via dashboard or REST API and add/remove/change attributes to a MetaModel, add/remove a whole MetaModel etc. In the background, ApiOmat executes a task every 60 seconds that checks if you've changed anything. If that's the case a commit and push to the repository will be triggered.
You can also trigger this push manually in the dashboard via the button labelled "Push dashboard changes to Git repository" (as you can see in the screenshot at the beginning of this page) or via Apidocs or cURL with a request to the endpoint: /modules/{moduleName}/gitPush. See https://apiomat.yourcompany.com/apidocs/index.html#!/modules/pushMetaModelChanges.
3. You change code and at the same time the data model gets changed via dashboard or REST API
Please read the sections "You change code" and "You change the data model via dashboard or REST API" first to understand the basic behaviour of ApiOmat when updating Git Native Modules.
When you update the data model via code and dashboard or REST API at the same time (or maybe multiple developers work on the same project), the following cases can occur:
-
You trigger the pull + deploy before the push task gets executed
-
The push task gets executed / you trigger it, and the conflict resolution is set to "force"
-
The push task gets executed / you trigger it, and the conflict resolution is set to "branch"
1. You trigger the pull + deploy before the push task gets executed
If you trigger the pull + deploy before the push task gets executed, no conflict will occur and the changes you made in the dashboard or via REST API will be overwritten with the code in the Git repository.
2. The push task gets executed / you trigger it, and the conflict resolution is set to "force"
In the apiomat.yaml configuration file you can set the conflict resolution mode to "force" by setting "gitConflictmode=force".
If the push task gets executed or you trigger it, the conflicting changes in the Git repository will be ignored and overwritten by the changes you made in the dashboard or via REST API.
3. The push task gets executed / you trigger it, and the conflict resolution is set to "branch"
In the apiomat.yaml configuration file you can set the conflict resolution mode to "branch" by setting "gitConflictmode=branch".
If the push task gets executed or you trigger it, the following will happen (in this order):
-
ApiOmat commits the changes you made via dashboard or REST API, tries to push to the Git repo and encounters the conflict
-
ApiOmat switches the branch from the current one (the one you used in the "pull + deploy" URL, e.g. "master") to a newly created branch called "AOM_MetamodelChange_<timestamp>", with <timestamp> being the current UNIX epoch time in milliseconds, and pushes the changes to that branch
-
ApiOmat switches back to the previous branch (the one you used in the "pull + deploy" URL, e.g. "master"), resets the files to the previous revision and pulls the changes from the Git repository (these are the ones you made in the code on your computer).
-
ApiOmat triggers a deployment of the updated data model
In case you want to use the changes made in the dashboard (or via REST API) instead of the changes in the Git repository, you can check out the branch that was created during conflict resolution and continue to work on that branch, or manually merge the branch into the current main branch in your Git client.
Using Maven
Since ApiOmat version 2.3, every module is delivered with a pom.xml, which will support you in the full lifecycle. Read more about the Maven integration.
Using Git with key-based auth via SSH
If you want to use key-based auth on your ApiOmat installation, you have to put the private key, which is authorized for your Git repositories, into the correct directory of the ApiOmat installation.
You have to put the private key (named id_rsa) into the .ssh folder of the home directory of the user that owns the Yambas process.
On a Linux system this is the tomcat7 user (so the home directory is /home/tomcat7 on a default installation). The file should be owned by the tomcat7 user and have the file mode 600 (read and write only allowed for that user).
On a Windows system the SSH directory is under C:/Users/Administrator/.ssh (if the tomcat process is configured to run under another user, replace "Administrator" with the other username)
We currently only support SSH keys with no additional password. When you add the module in the Dashboard, simply leave the Git password field empty.