From 274119454d405bd63263c87652a1f70204e85ede Mon Sep 17 00:00:00 2001 From: zbhupav <51440892+zbhupav@users.noreply.github.com> Date: Tue, 14 Jan 2020 12:37:25 +0530 Subject: [PATCH] Documentation of REMReM generate in OpenSource (#155) --- README.md | 12 +- wiki/markdown/index.md | 18 +++ wiki/markdown/installation.md | 12 ++ wiki/markdown/logging.md | 14 ++ wiki/markdown/usage.md | 7 + wiki/markdown/usage/configuration.md | 159 ++++++++++++++++++++ wiki/markdown/usage/generate-cli.md | 177 ++++++++++++++++++++++ wiki/markdown/usage/service.md | 212 +++++++++++++++++++++++++++ 8 files changed, 609 insertions(+), 2 deletions(-) create mode 100644 wiki/markdown/index.md create mode 100644 wiki/markdown/installation.md create mode 100644 wiki/markdown/logging.md create mode 100644 wiki/markdown/usage.md create mode 100644 wiki/markdown/usage/configuration.md create mode 100644 wiki/markdown/usage/generate-cli.md create mode 100644 wiki/markdown/usage/service.md diff --git a/README.md b/README.md index 75e6fdf0..9f214ce7 100644 --- a/README.md +++ b/README.md @@ -27,9 +27,17 @@ Eiffel REMReM Generate takes a partial message in JSON format, validates it and # Documentation -1. [**Running RemRem-Generate service**]() - - [**Run in Docker**](wiki/markdown/docker.md) +1. [**Introduction**](wiki/markdown/index.md) +2. [**Pre-requisites**](wiki/markdown/index.md#Pre-requisites) + +3. [**Installation**](wiki/markdown/installation.md) + +4. [**Run in Docker**](wiki/markdown/docker.md) + +5. [**Usage**](wiki/markdown/usage.md) + +6. [**Logging**](wiki/markdown/logging.md) # About this repository The contents of this repository are licensed under the [Apache License 2.0](./LICENSE). diff --git a/wiki/markdown/index.md b/wiki/markdown/index.md new file mode 100644 index 00000000..85ba0388 --- /dev/null +++ b/wiki/markdown/index.md @@ -0,0 +1,18 @@ +## Introduction + +REMReM (**REST Mailbox for Registered Messages**) is a set of tools that can be used to generate validated Eiffel messages and publish them on a RabbitMQ message bus. They can be run as micro services or as stand-alone CLI versions. For more details on the micro services and the REMReM design, see [Eiffel REMReM](https://github.com/eiffel-community/eiffel-remrem) + +Eiffel REMReM Generate takes a partial message in JSON format, validates it and adds mandatory fields before outputting a complete, valid Eiffel message. + + +## Pre-requisites + +* JDK 8 +* Tomcat 8 + +For supporting latest features, Eiffel REMReM Generate should use the latest version of [Eiffel REMReM Semantics](https://github.com/eiffel-community/eiffel-remrem-semantics). + +## Components + +* REMReM Generate CLI (Command Line Interface) +* REMReM Generate Service \ No newline at end of file diff --git a/wiki/markdown/installation.md b/wiki/markdown/installation.md new file mode 100644 index 00000000..e76da833 --- /dev/null +++ b/wiki/markdown/installation.md @@ -0,0 +1,12 @@ +# Installation +Eiffel REMReM Generate is maven project and can be built by executing following command: + +``` +mvn clean install +``` + +Binary is released via [jitPack](https://jitpack.io/#eiffel-community/eiffel-remrem-generate) + +The latest REMReM Generate CLI binary can be downloaded via [generate-cli.jar](https://jitpack.io/#eiffel-community/eiffel-remrem-generate) + +The latest REMReM Generate Service binary can be downloaded via [generate-service.war](https://jitpack.io/#eiffel-community/eiffel-remrem-generate) \ No newline at end of file diff --git a/wiki/markdown/logging.md b/wiki/markdown/logging.md new file mode 100644 index 00000000..2b15795b --- /dev/null +++ b/wiki/markdown/logging.md @@ -0,0 +1,14 @@ +## Logging + +REMReM Generate application logging is implemented using the logback-classic. It requires user to configure the logback.xml file. +When used without logback.xml log messages will look as below: + +``` + %PARSER_ERROR[wEx]%PARSER_ERROR[clr] %PARSER_ERROR[clr] %PARSER_ERROR[clr] %PARSER_ERROR[clr] + %PARSER_ERROR[clr] %PARSER_ERROR[clr] %PARSER_ERROR[clr] +``` +To configure the logback.xml file use **-Dlogging.config=path/logback.xml** + +To get info about logback configurations see [here](https://logback.qos.ch/manual/configuration.html). + +To get sample logback.xml to use see [here](https://eiffel-community.github.io/eiffel-remrem-generate/logback/logback-sample.xml). \ No newline at end of file diff --git a/wiki/markdown/usage.md b/wiki/markdown/usage.md new file mode 100644 index 00000000..d9f852b2 --- /dev/null +++ b/wiki/markdown/usage.md @@ -0,0 +1,7 @@ +## Usage + +To get information about configuration and usage of **REMReM Generate CLI** see [here](../markdown/usage/generate-cli.md). + +To get information about configuration and usage of **REMReM Generate Service** see [here](../markdown/usage/service.md). + +Examples used here in the Eiffel events can be found in the protocol repository. Please follow [eiffel syntax](https://github.com/eiffel-community/eiffel/tree/master/eiffel-syntax-and-usage) and [eiffel vocabulary](https://github.com/eiffel-community/eiffel/tree/master/eiffel-vocabulary). diff --git a/wiki/markdown/usage/configuration.md b/wiki/markdown/usage/configuration.md new file mode 100644 index 00000000..a09ab763 --- /dev/null +++ b/wiki/markdown/usage/configuration.md @@ -0,0 +1,159 @@ +## Configuration + +#### Running and configuring RemRem-Generate without Tomcat installation + +It is also possible to execute RemRem-Generate without external Tomcat installation and using the embedded tomcat in Spring application instead. + +If RemRem-Generate is executed without external Tomcat installation, the configuration should be based on Spring application properties, see service/src/main/resources/application.properties file for available properties. + +If running with java command, example: + +``` +java -jar service/target/generate-service-x.x.x.war --properties.parameter1=value --properties.parameter2=value --properties.parameter3=value ...... +``` + +It is also possible to provide path to the spring properties file: + +``` +java -jar service/target/generate-service-x.x.x.war --spring.config.location=path/to/applicattion.propeties +``` + +Second option to execute RemRem-Generate is to execute maven commands from the source code root folder, example: + +``` +mvn spring-boot:run -Dspring-boot.run.arguments=--properties.parameter1=value,--properties.parameter2=value,--properties.parameter3=value,--properties.parameter4=value ...... +``` + +When using maven command, Spring properties can also be changed by editing service/src/main/resources/application.properties file. + +#### Running and configuring in Tomcat + +Eiffel REMReM Service **generate-service.war** file should be deployed in Tomcat Server. For doing this, generate-service.war file should deployed in directory: _tomcat/webapps_. + +Configuration is done in Tomcat using a config.properties file: _tomcat/conf/config.properties_. + +**NOTE:** in each example assuming the generate-service.war is deployed in tomcat as **generate**. + +**NOTE:** for other than eiffelsemantics protocol, provide the Java opts as: + +``` +set JAVA_OPTS="-Djava.ext.dirs=/path/to/jars/" in catalina.sh +``` + +**NOTE:** in the above example, protocol jar file must be present inside "/path/to/jars/" folder. + +**NOTE:** "-Djava.ext.dirs" is no longer working in some JAVA8 versions and in JAVA9. So users should create a wrapper project to include both Generate/Publish and their protocol in or place the protocol library in the folder for external dependencies of their JVM installation. + +### Jasypt configurations + +Jasypt Spring Boot provides Encryption support for property sources(passwords, secret info ..etc) in Spring Boot Applications. To support this functionality in our application we need to add the following property in property file + +**jasypt.encryptor.password: The key value which was used while encrypting the original password** + +The above encryptor password must be same for both encryption and decryption of the original password(ldap,rabbitmq...etc) +The encryptor password will be used by jasypt-spring-boot library in application to decrypt the encrypted password at runtime. + +#### How to encrypt the password: + +``` +1) Download the jasypt jar file from any of the below locations +[Link to Jasypt](http://www.jasypt.org/download.html) (or) [Link to Maven](https://mvnrepository.com/artifact/org.jasypt/jasypt/1.9.2) + +2) Execute the below command to generate Jasypt encrypted password + java -cp jasypt-1.9.2.jar org.jasypt.intf.cli.JasyptPBEStringEncryptionCLI input="any password" password=any intermediate key + +input : any password which we want to encrypt(Ex: rabbitmq password, ldap user password, etc...) +password: A Jasypt key used to encrypt the above input( The Jasypt key can be anything, but make sure same key to be used for decryption) + +Example: + Run the below command in Command line + + java -cp jasypt-1.9.2.jar org.jasypt.intf.cli.JasyptPBEStringEncryptionCLI input="dummyPassword" password=dummy + +output: + ----ENVIRONMENT----------------- + + Runtime: Oracle Corporation Java HotSpot(TM) 64-Bit Server VM 25.144-b01 + + ----ARGUMENTS------------------- + + algorithm: PBEWithMD5AndDES + input: dummyPassword + password: dummy + + ----OUTPUT---------------------- + + euJcvto7NtCDiWT7BKFW0A== +``` + +Use the above encrypted password in your property file like this **ENC(encrypted password)** + + **Ex:rabbitmq.password: ENC(euJcvto7NtCDiWT7BKFW0A ==)** + +**Note: REMReM will work without jasypt encryption also but if you have encrypted any text using jasypt library then** _jasypt.encryptor.password_ **property should be present in property file** + +### Ldap authentication configurations + + Active Directory authentication can be enabled for the REMReM REST service by setting the configuration property + + **activedirectory.generate.enabled:true**. + +**NOTE:** it is recommended to disable ldap authentication for REMReM Publish Service for correct work of REMReM Publish Service endpoint + + **/generateAndPublish.** + +``` +activedirectory.generate.enabled: +activedirectory.ldapUrl: +activedirectory.managerPassword: +activedirectory.managerDn: +activedirectory.rootDn: +activedirectory.userSearchFilter: +``` + + **LDAP authentication without Base64 encryption of user details::** + +``` + $ curl -XPOST -H "Content-Type: application/json" --user username:password --data @ActivityCanceled.json http://localhost:8080/generate-service/eiffelsemantics?msgType=eiffelactivitycanceled +``` + + **NOTE:** each HTTP request must then include an Authorization header with value + + **Basic ** + +**LDAP authentication with Base64 encryption of user details::** + +``` +$ curl -XPOST -H "Content-Type: application/json" -H 'Authorization: Basic cGFzc3dvcmQ=' --data @ActivityCanceled.json http://localhost:8080/generate-service/eiffelsemantics?msgType=eiffelactivitycanceled +``` + +### Event Repository Lookup Configurations + +ER lookup configurations define whether to enable querying towards Event Repository or not. ER lookup configurations are enabled by configuring below property in configuration file. + +``` + event-repository.enabled : +``` + +**NOTE:** Allowed value for _event-repository.enabled_ is _true/false_.If the value is not one of this the service will be terminated. + +If _event-repository.enabled_ is false then REMReM Generate will not Lookup ER data. Refer below snippet for instance, + +``` + event-repository.enabled : false + event-repository.url : http(s)://:/ +``` + +If _event-repository.enabled_ is true then Event Repository URL should be mandatory. + +``` + event-repository.enabled : true + event-repository.url : http(s)://:/ +``` + +**NOTE:** If Lookup configurations are enabled and EventRepository URL is not provided then the remrem service gets terminated. + +``` + event-repository.enabled : true + event-repository.url : +``` \ No newline at end of file diff --git a/wiki/markdown/usage/generate-cli.md b/wiki/markdown/usage/generate-cli.md new file mode 100644 index 00000000..eb37fcbe --- /dev/null +++ b/wiki/markdown/usage/generate-cli.md @@ -0,0 +1,177 @@ +# REMReM Generate CLI + +## Usage + +For using Eiffel REMReM Generate CLI self executing **generate-cli.jar** file should be executed in command line with parameters described below. + +``` +java -jar generate-cli.jar -h + +You passed help flag. +usage: java -jar + + -d,--debug enable debug traces + + -f,--content_file message content file + + -h,--help show help + + -json,--json_content JSON content + + -mp,--messaging_protocol name of messaging protocol to be used, e.g. eiffelsemantics + + -r,--response_file file to store the response in, optional + + -t,--message_type message type, mandatory if -f or -json is given + + -v,--list_versions lists the versions of generate and all loaded protocols + ``` + + +**Generate templates for Eiffel REMReM Semantics to be used are available [here.](https://github.com/eiffel-community/eiffel-remrem-semantics)** + +The message must exist in a JSON file, for example **_eiffelactivityfinished.json_** might contain the following message: + +``` +{ + "msgParams": { + "meta": { + "type": "EiffelActivityFinishedEvent", + "version": "3.0.0", + "tags": [""], + "source": { + "domainId": "", + "host": "", + "name": "", + "uri": "" + } + } + }, + "eventParams": { + "data": { + "outcome": { + "conclusion": "required if outcome present, can be one of SUCCESSFUL,UNSUCCESSFUL,FAILED,ABORTED,TIMED_OUT,INCONCLUSIVE", + "description": "" + }, + "persistentLogs": [{ + "name": "required if persistentLogs present", + "uri": "required if persistentLogs present" + }], + "customData": [{ + "key": "required if customData present", + "value": "required if customData present" + }] + }, + "links": [{ + "type": "ACTIVITY_EXECUTION", + "target": "required - UUID of EiffelActivityTriggeredEvent" + }, + { + "type": "CAUSE or CONTEXT or FLOW_CONTEXT - optional", + "target": "required - UUID if type is present" + }] + } +} +``` + +## Examples + +Typical examples of usage Eiffel REMReM Generate CLI are described below. + +##### With input from the example file shown above and output to a file: + +``` +$ java -jar generate-cli.jar -f eiffelactivityfinished.json -t eiffelactivityfinishedevent -r output.json +``` + +##### Same example, but output the result on the console: + +``` +$ java -jar generate-cli.jar -f eiffelactivityfinished.json -t eiffelactivityfinished +``` + +##### Same example, but this time the data is supplied as a command line argument: + +``` +$ java -jar generate-cli.jar -t eiffelactivityfinished -json {"msgParams":{"meta":{"type":"EiffelActivityFinishedEvent","tags":["tag1","tag2"],"source":{"domainId":"example.domain","host":"host","name":"name","uri":"http://java.sun.com/j2se/1.3/","serializer":"pkg:maven/com.github.eiffel-community/eiffel-remrem-semantics@2.0.0"},"security":{"sdm":{"authorIdentity":"test","encryptedDigest":"sample"}}}},"eventParams":{"data":{"outcome":{"conclusion":"SUCCESSFUL"},"persistentLogs":[{"name":"firstLog","uri":"http://myHost.com/firstLog"},{"name":"otherLog","uri":"isbn:0-486-27557-4"}]},"links":[{"type":"ACTIVITY_EXECUTION","target":"aaaaaaaa-bbbb-5ccc-8ddd-eeeeeeeeeee1"}]}} +``` + +##### For loading protocol jars other than _eiffelsemantics_: + +``` +$ java -Djava.ext.dirs="/path/to/jars/" -jar generate-cli.jar -f eiffeljobfinished.json -t eiffeljobfinished -mp protocoltype +``` + +**NOTE:** in the above example, protocol jar file must be present inside "/path/to/jars/" folder. + +**NOTE:** `-Djava.ext.dirs` is no longer working in some JAVA8 versions and in JAVA9. So users should create a wrapper project to include both Generate/Publish and their protocol in or place the protocol library in the folder for external dependencies of their JVM installation. + +Typical output for these examples is: + +``` +[ + { + "meta":{ + "id":"534c0b84-9348-422b-8bee-c4023488cd5d", + "type":"EiffelActivityFinishedEvent", + "version":"3.0.0", + "time":1521534547653, + "tags":[ + "tag1", + "tag2" + ], + "source":{ + "domainId":"example.domain", + "host":"host", + "name":"name", + "serializer":"pkg:maven/com.github.eiffel-community/eiffel-remrem-semantics@2.0.0", + "uri":"http://java.sun.com/j2se/1.3/" + }, + "security":{ + "sdm":{ + "authorIdentity":"test", + "encryptedDigest":"sample" + } + } + }, + "data":{ + "outcome":{ + "conclusion":"SUCCESSFUL" + }, + "persistentLogs":[ + { + "name":"firstLog", + "uri":"http://myHost.com/firstLog" + }, + { + "name":"otherLog", + "uri":"isbn:0-486-27557-4" + } + ], + "customData":[ + + ] + }, + "links":[ + { + "type":"ACTIVITY_EXECUTION", + "target":"aaaaaaaa-bbbb-5ccc-8ddd-eeeeeeeeeee1" + } + ] + } +] +``` + +## Exit Codes + +If CLI fails internally before trying to generate Eiffel message, user will get exit code. Exit codes are described in the table below. + +| Exit code | Description | +| -------------| -------------------------------------------------------------------------------------- | +| 1 | User will get this exit code in case of some error that is not described below | +| 2 | Some CLI options are missed | +| 3 | Unable to read content from passed file path | +| 4 | Unable to read passed JSON string from command line | +| 5 | Unable to send JSON message to message service | +| 6 | Passed message protocol is not correct | + diff --git a/wiki/markdown/usage/service.md b/wiki/markdown/usage/service.md new file mode 100644 index 00000000..d282f9a9 --- /dev/null +++ b/wiki/markdown/usage/service.md @@ -0,0 +1,212 @@ +# REMReM Generate Service + +## Usage + +REMReM Generate Service allows generating of Eiffel messages that will be send by [Eiffel REMReM Publish](https://github.com/eiffel-community/eiffel-remrem-publish) to RabbitMQ. + +Information about the REMReM Generate Service all endpoints can be got and easily accessed using next links: + +``` +http://:// +``` + +or + +``` +http://://swagger-ui.html +``` + +Example: + +``` +http://localhost:8080/generate/ +``` + +Configuration of REMReM Generate can be found [here](configuration.md) + + +Available REST resources for REMReM Generate Service are described below: + +| Resource | Method | Parameters | Request body | Description | +|-----------------------|--------|---------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| /mp | POST | mp - message protocol, required msgType - Eiffel event type, required failIfMultipleFound - default: false failIfNoneFound - default: false | { "msgParams": {"meta": {# Matches the meta object }},"eventParams": {"data": {# Matches the data object},"links": { # Matches the links object } }} | This endpoint is used to generate Eiffel events and then the obtained event could be published by [Eiffel REMReM Publish](https://github.com/eiffel-community/eiffel-remrem-publish). | +| /event_types/{mp} | GET | mp - message protocol, required | | This endpoint is used to obtain Eiffel event types implemented in [Eiffel REMReM Semantics](https://github.com/eiffel-community/eiffel-remrem-semantics). | +| /template/{type}/{mp} | GET | type - Eiffel event type mp - message protocol, required | | This endpoint is used to obtain Eiffel event templates implemented in [Eiffel REMReM Semantics](https://github.com/eiffel-community/eiffel-remrem-semantics). | +| /versions | GET | | | This endpoint is used to get versions of generate service and all loaded protocols versions in JSON format. | + + +## Examples + +Typical examples of usage Eiffel REMReM Generate Service endpoints are described below. + +You can use command line tools like [curl](https://curl.haxx.se/) or some plugin for your favorite browser. For example: + +* [Postman](https://chrome.google.com/webstore/detail/postman/fhbjgbiflinjbdggehcddcbncdddomop) for Chromium-based browsers +* [HttpRequester](https://addons.mozilla.org/en-US/firefox/addon/httprequester/) for Firefox + +### Examples for `/mp` endpoint + +#### Given one message in file _body-single.json_: + +``` +curl -XPOST -H "Content-Type: application/json" --data @body-single.json http://localhost:8080/generate-service/eiffelsemantics?msgType=eiffelactivityfinished +``` + +Result: + +``` +{"meta":{"id":"29f9b8b1-9d4b-41cf-9f42-4e6157850757","type":"EiffelActivityFinishedEvent","version":"3.0.0","time":1499076743638,"tags":["tag1","tag2"],"source":{"domainId":"example.domain","host":"host","name":"name","serializer":"pkg:maven/com.github.eiffel-community/eiffel-remrem-semantics@2.0.4","uri":http://java.sun.com/j2se/1.3/"}}"data":{"outcome":{"conclusion":"SUCCESSFUL","description":"The Result was Successful"},"persistentLogs":[],"customData":[{"key":"translatedSourceID","value":"29f9b8b1-9d4b-41cf-9f42-4e6157850757"}]},"links":[{"type":"ACTIVITY_EXECUTION","target":"69538470-4c3f-4c16-b84e-64ff0275f6fc"},{"type":"FLOW_CONTEXT","target":"ea82a50c-53bb-4d0c-8f03-b50fb83feb16"}]} +``` + +#### Example with event body passed to service: + +``` +curl -H "Content-Type: application/json" -X POST -d '{"msgParams": {"meta": {"type": "EiffelActivityFinishedEvent", "tags": ["tag1","tag2"], "source": {"domainId": "example.domain", "host": "host", "name": "name", "uri":http://java.sun.com/j2se/1.3/"}}}, "eventParams": {"data": {"outcome": {"conclusion": "SUCCESSFUL"}, "persistentLogs": [], "links": [{"type": "ACTIVITY_EXECUTION", "target": "69538470-4c3f-4c16-b84e-64ff0275f6fc"}]}}' http://localhost:8080/generate-service/eiffelsemantics?msgType=eiffelactivityfinished +``` +Result: + +``` +{"meta":{"id":"29f9b8b1-9d4b-41cf-9f42-4e6157850757","type":"EiffelActivityFinishedEvent","version":"3.0.0","time":1499076743638,"tags":["tag1","tag2"],"source":{"domainId":"example.domain","host":"host","name":"name","serializer":"pkg:maven/com.github.eiffel-community/eiffel-remrem-semantics@2.0.4","uri":http://java.sun.com/j2se/1.3/"}}"data":{"outcome":{"conclusion":"SUCCESSFUL","description":"The Result was Successful"},"persistentLogs":[],"customData":[{"key":"translatedSourceID","value":"29f9b8b1-9d4b-41cf-9f42-4e6157850757"}]},"links":[{"type":"ACTIVITY_EXECUTION","target":"69538470-4c3f-4c16-b84e-64ff0275f6fc"},{"type":"FLOW_CONTEXT","target":"ea82a50c-53bb-4d0c-8f03-b50fb83feb16"}]} +``` + +### Examples for `/event_types/{mp}` endpoint + +#### Retrieve the event types: + +``` +curl -X GET --header 'Accept: application/json' 'http://localhost:8080/generate-service/event_types/eiffelsemantics' +``` + +Result: + +``` +["EiffelArtifactPublishedEvent","EiffelActivityFinishedEvent","EiffelActivityCanceledEvent","EiffelArtifactCreatedEvent","EiffelActivityTriggeredEvent","EiffelConfidenceLevelModifiedEvent","EiffelActivityStartedEvent","EiffelAnnouncementPublishedEvent","EiffelCompositionDefinedEvent","EiffelTestCaseCanceledEvent","EiffelTestCaseTriggeredEvent","EiffelTestExecutionRecipeCollectionCreatedEvent","EiffelEnvironmentDefinedEvent","EiffelFlowContextDefinedEvent","EiffelSourceChangeCreatedEvent","EiffelSourceChangeSubmittedEvent","EiffelTestCaseFinishedEvent","EiffelTestCaseStartedEvent","EiffelTestSuiteFinishedEvent","EiffelTestSuiteStartedEvent","EiffelIssueVerifiedEvent","EiffelArtifactReusedEvent","EiffelServiceStoppedEvent","EiffelServiceStartedEvent","EiffelServiceReturnedEvent","EiffelServiceDiscontinuedEvent","EiffelServiceDeployedEvent","EiffelServiceAllocatedEvent","EiffelArtifactDeployedEvent","EiffelAlertAcknowledgedEvent","EiffelAlertCeasedEvent","EiffelAlertRaisedEvent"] +``` + +### Examples for `/template/{type}/{mp}` endpoint + +#### Retrieve the event template: + +``` +curl -X GET --header 'Accept: application/json' 'http://localhost:8080/generate-service/template/EiffelArtifactPublishedEvent/eiffelsemantics' +``` + +Result: + +``` +{"msgParams": {"meta": {"type": "EiffelActivityFinishedEvent","version": "3.0.0","tags": [""],"source": {"domainId": "","host": "","name": "","uri": ""}}},"eventParams": {"data": {"outcome": {"conclusion": "required if outcome present, can be one of SUCCESSFUL,UNSUCCESSFUL,FAILED,ABORTED,TIMED_OUT,INCONCLUSIVE","description": ""},"persistentLogs": [{"name": "required if persistentLogs present","uri": "required if persistentLogs present"}],"customData": [{"key": "required if customData present","value": "required if customData present"}]},"links": [{"type": "ACTIVITY_EXECUTION","target": "required - UUID of EiffelActivityTriggeredEvent"},{"type": "CAUSE or CONTEXT or FLOW_CONTEXT - optional","target": "required - UUID if type is present"}]}} +``` + +### Examples for `/versions` endpoint + +``` +curl -H "Content-Type: application/json" -X GET http://localhost:8080/generate/versions +``` + +Result: + +``` +{"serviceVersion":{"version":"x.x.x"},"endpointVersions":{"semanticsVersion":"x.x.x"}} +``` + +## Status Codes + +The response generated will have internal status codes for each and every event based on the input JSON provided. + +Status codes are generated according to the below table. + +| Status code | Result | Message | Comment | +|-------------|-----------------------|---------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------| +| 200 | OK | | Event generated successfully | +| 400 | Bad Request | Could not read document: Unrecognized token | Malformed JSON (missing braces or wrong event type, etc..), client need to fix problem in event before submitting again | +| 404 | Not Found | Requested template is not available | The endpoint is not found, or template for specified event type is not found | +| 406 | Not Acceptable | No event id found with ERLookup properties | Is returned if no event id fetched from configured event repository in REMReM generate. | +| 417 | Expectation Failed | Multiple event ids found with ERLookup properties | Is returned if multiple event ids fetched from configured event repository in REMReM generate. | +| 500 | Internal Server Error | Internal server error | When REMReM Generate is down, possible to try again later when server is up | +| 503 | Service Unavailable | "No protocol service has been found registered" | When specified message protocol is not loaded | + + +## Lookups + +Presently, to generate Eiffel messages, Eiffel REMREM-Generate is being used. This process requires input mapping exactly one-to-one to Eiffel message Schema. + +The "Link" field of Eiffel Message requires UUIDs of earlier sent events to link to. Passing these UUID's each time is a little bit difficult, some times user lookup the ER and manually place those IDs in REMReM Generate semi-structured event. In order to resolve this , we need to provide LOOKUP's for the Link's field ,which will have eventType and Properties. eventType will contain type of event. + +Properties will contain any field of event mentioned in eventType or RepoUri or artifact identity (Purl identity including version) to Eiffel, which will make sure it is linked to the correct events. The lookups are used in filling the information for links, which will help users to know what event they want to query with the parameters so that they are automatically fetched and linked by Generate instead of the users adding them as a mandatory param when generating events. + +_parameters_ specified should be enough to replace the listed event id as input will help to prepare the Query to ER and Lookup the ER data. + +### Example: + +As a User, I want to place the LINK type ARTIFACT to Event ID of EiffelArtifactCreatedEvent from Event Repository. The user passes the below template information to REMReM Generate, REMReM Generate will Query to configured Event Repository and place the event ID in LINK's and generate the Eiffel message. + +#### Templates for LOOKUPS : + +``` + "links":[ + { + "type": "ARTIFACT", + "%lookup%": { + "eventType": "EiffelArtifactCreatedEvent", + "properties": [ + { "data.identity": "some purl identifier defining the artifact" }] + } + }] +``` + +#### ER Query will look like: + +``` +https://localhost:8080/eventrepository/events/?meta.type=EiffelArtifactCreatedEvent&data.identity=some purl identifier defining the artifact +``` + +#### Examples for Lookups: + +**Example 1:** + +``` + "links":[ + { + "type": "ARTIFACT", + "%lookup%": { + "eventType": "EiffelArtifactCreatedEvent", + "properties": [ + { "data.identity": "pkg:maven/test/testartifact@0.0.21" }] + } + }] +``` + +**Example 2 :** + +``` + "links":[ + { + "type": "ARTIFACT", + "%lookup%": { + "eventType": "EiffelArtifactCreatedEvent", + "properties": [ + { "data.identity": "pkg:maven/test/batik-anim@1.9.1" }] + } + }] +``` + +**Example 3 (For SourceChangeCreated/SourceChangeSubmitted Events Identifier will be repoUri):** + +``` + "links":[ + { + "type": "CHANGE", + "%lookup%": { + "eventType": "EiffelSourceChangeCreatedEvent", + "properties": [ + { "data.identity": "data.gitIdentifier.repoUri": "https://gerrit.ericsson.se" }] + } + }] +``` + +#### Lookups are provided with two options: + +| Options | Default Value | Description | +|----------------------|---------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| failIfMultipleFound: | False | If value is set to false, REMReM generates event if multiple event ids found or no event id fetched from the event repository configured in generate and adds them in links section of the target field. If value is set to true, if only one event is found then REMReM generates the event successfully and if multiple event ids are found then REMReM fails to generate any event and displays relevant error message to the user. | +| failIfNoneFound: | False | If value is set to true, no event ids fetched from event repository , REMReM fails to generate any event and displays relevant error message to the user. If value is set to false,REMReM generates event if no event found or atleast one event fetched from the event repository configured in configuration file. | \ No newline at end of file