Repository: incubator-unomi Updated Branches: refs/heads/master c7c3cad6e -> 95d003084
UNOMI-202 : Added documentation Project: http://git-wip-us.apache.org/repos/asf/incubator-unomi/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-unomi/commit/95d00308 Tree: http://git-wip-us.apache.org/repos/asf/incubator-unomi/tree/95d00308 Diff: http://git-wip-us.apache.org/repos/asf/incubator-unomi/diff/95d00308 Branch: refs/heads/master Commit: 95d003084a3b960c676365cb60b47302755d09a3 Parents: c7c3cad Author: tdraier <dra...@apache.org> Authored: Thu Oct 11 15:06:12 2018 +0200 Committer: tdraier <dra...@apache.org> Committed: Thu Oct 11 15:06:12 2018 +0200 ---------------------------------------------------------------------- manual/src/main/asciidoc/custom-extensions.adoc | 81 +++++++++++++++++++- 1 file changed, 77 insertions(+), 4 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-unomi/blob/95d00308/manual/src/main/asciidoc/custom-extensions.adoc ---------------------------------------------------------------------- diff --git a/manual/src/main/asciidoc/custom-extensions.adoc b/manual/src/main/asciidoc/custom-extensions.adoc index 20faa72..41c7102 100644 --- a/manual/src/main/asciidoc/custom-extensions.adoc +++ b/manual/src/main/asciidoc/custom-extensions.adoc @@ -74,9 +74,9 @@ is needed to build your application. ==== Deployment and custom definition -When you deploy a custom bundle with a custom definition (see "Predefined xxx" chapters under) for the first time, the definition will automatically be deployed at your bundle start event *if it does not exist*, after that if you redeploy the same bundle there are two cases: -1. Your bundle *is a SNAPSHOT* then every time you redeploy it the definition will be redeployed -2. Your bundle *is NOT a SNAPSHOT* then the definition will not be redeployed, but you can redeploy it manually using the command `unomi:deploy-definition <bundleId> <fileName>` +When you deploy a custom bundle with a custom definition (see "Predefined xxx" chapters under) for the first time, the definition will automatically be deployed at your bundle start event *if it does not exist*. +After that if you redeploy the same bundle, the definition will not be redeployed, but you can redeploy it manually using the command `unomi:deploy-definition <bundleId> <fileName>` If you need to modify an existing +definition when deploying the module, see <<Migration patches>>. ==== Predefined segments @@ -416,4 +416,77 @@ src/main/resources/OSGI-INF/blueprint/blueprint.xml You can find the implementation of the two classes here : * https://github.com/apache/incubator-unomi/blob/master/plugins/baseplugin/src/main/java/org/apache/unomi/plugins/baseplugin/conditions/MatchAllConditionESQueryBuilder.java[org.apache.unomi.plugins.baseplugin.conditions.MatchAllConditionESQueryBuilder] -* https://github.com/apache/incubator-unomi/blob/master/plugins/baseplugin/src/main/java/org/apache/unomi/plugins/baseplugin/conditions/MatchAllConditionEvaluator.java[org.apache.unomi.plugins.baseplugin.conditions.MatchAllConditionEvaluator] \ No newline at end of file +* https://github.com/apache/incubator-unomi/blob/master/plugins/baseplugin/src/main/java/org/apache/unomi/plugins/baseplugin/conditions/MatchAllConditionEvaluator.java[org.apache.unomi.plugins.baseplugin.conditions.MatchAllConditionEvaluator] + +==== Migration patches + +You may provide patches on any predefined items by simply adding a JSON file in : + +[source] +---- +src/main/resources/META-INF/cxs/patches +---- + +These patches will be applied when the module will be deployed the first time. +They allow to modify an item, that would have been previously deployed on unomi by a previous version of the extension or by something else. + +Each patch must have a unique id - unomi will use this id to remember that the patch has already been applied. It can also be used to reapply the patch when need by using the karaf command `unomi:deploy-definition` + +A patch also need to reference the item to patch by setting `patchedItemId` and `patchedItemType`, and an operation that tells what the patch should do. + +You can apply a patch in http://jsonpatch.com/[json-patch] format in the `data` field, and by specifying operation `patch` like in this example : + +[source] +---- +{ + "itemId": "firstName-patch1", + "patchedItemId": "firstName", + "patchedItemType": "propertyType", + "operation": "patch", + "data": [ + { + "op": "replace", "path": "/defaultValue", "value": "foo" + } + ] +} +---- + +If you need to completely redeploy a definition, you can use the `override` operation and put the definition in `data` + +[source] +---- +{ + "itemId": "gender-patch1", + "patchedItemId": "gender", + "patchedItemType": "propertyType", + "operation": "override", + "data": { + "metadata": { + "id": "gender", + "name": "Gender", + "systemTags": [ + "properties", + "profileProperties" + ] + }, + "type": "string", + "defaultValue": "foo", + "automaticMappingsFrom": [ ], + "rank": "105.0" + } +} +---- + +It is also possible to simply remove an item by using the operation `remove` : + +[source] +---- +{ + "itemId": "firstName-patch2", + "patchedItemId": "firstName", + "patchedItemType": "propertyType", + "operation": "remove" +} +---- + +Patches can also be deployed at runtime by using the REST endpoint /patch/apply .
