Update template descriptions and add keywords to improve refactorings suggestions

[philippfromme]

What should we do?

The ✨ feature for selected elements in Web Modeler suggests connectors based on an element's name. The suggestions are based on the name and description of the connector templates and therefore the quality of suggestions depends on those.

The latest version of the ✨ also takes into account keywords that were added to a template. For example, the following template

{
  "$schema": "https://unpkg.com/@camunda/zeebe-element-templates-json-schema/resources/schema.json",
  "name": "Twitter Connector",
  "id": "io.camunda.connectors.Twitter",
  "version": 1,
  "description": "Post and manage tweets on Twitter",
  "metadata": {
    "keywords": [
      "create tweet",
      "delete tweet",
      "quote tweet",
      "reply to tweet",
      "retweet"
    ]
  },
  "category": {
    "id": "connectors",
    "name": "Connectors"
  },
  "appliesTo": [
    "bpmn:Task"
  ],
  "properties": []
}

has a keywords field with relevant keywords. If an element's name mentions replying to a tweet the connector will be suggested based on the matching keyword.

Why should we do it?

To improve the quality of suggestions.

Related to https://github.com/bpmn-io/refactorings/pull/27

[philippfromme]

@chillleader @Oleksiivanov @igpetrov What is the source of truth for element template descriptions? I couldn't find anything other than the templates themselves?

[YanaSegal]

@philippfromme depends where:

• append element description is from the template
• browse marketplace coming from the marketplace page

[philippfromme]

Yes, I'm talking about the templates themselves. But since they are generated I was wondering where the descriptions are coming from and who is responsible for them.

[YanaSegal]

The template creator is responsible for providing the description.

[crobbins215]

@johnBgood is this something you could pick up and discuss with @philippfromme? @philippfromme is happy to help and hopefully, this would be a quick pick to get done, it's going to improve the connector suggestions.

[johnBgood]

@philippfromme It's generated using the Element Template Generator (ETG). The ETG parse our Java models and generates the json files. Each Outbound Connector extends OutboundConnectorFunction, for instance the SQL Connector. In this file you will find a property named inputDataClass which points the Data class (JdbcRequest in this case). You can then check the different properties, and will find a description property (not always though).

For instance in the JdbcRequestData record.

Please let me know if it's clear enough, I'm happy to discuss it more.

[philippfromme]

Okay, I finally found what I was looking for. The descriptions are in the source files: https://github.com/search?q=repo%3Acamunda%2Fconnectors%20description%20%3D&type=code. For example: https://github.com/camunda/connectors/blob/fcc8705b7f329b9667218b76104aef83ec8968b3/connectors/jdbc/src/main/java/io/camunda/connector/jdbc/outbound/JdbcFunction.java#L26

And to add the new keywords property can I just add it to the source files or does it need to be supported by the meta model first?

[johnBgood]

I think you missed my last message :'( We need to support keyword in the ETG first. It's not huge but it still needs to be done.

[philippfromme]

@johnBgood Sorry, I did actually see your message and based on it I was able to find what I was looking for, so thank you. 😃

[philippfromme]

@johnBgood Would it look something like this?

[johnBgood]

@philippfromme I adjusted the PR a bit, you will find how the element templates for the JDBC Connector have been updated.

Let me know if it's what you wanted :)

[philippfromme]

@johnBgood Thanks for helping out with that!

[philippfromme]

@johnBgood For connectors like the Asana connector there seems to be a template only. Are these not generated and therefore have to be modified directly?

[johnBgood]

@philippfromme exactly, some connectors are based on other connectors (the REST connector in this case).

You can see it looking at these lines:

 {
      "type": "Hidden",
      "value": "io.camunda:http-json:1",
      "binding": {
        "type": "zeebe:taskDefinition",
        "property": "type"
      }
    },

http-json:1 is the REST Connector.

Just putting this here for context, you're right you need to update the JSON file directly for these connectors.

[philippfromme]

@johnBgood Another question: In some cases (e.g. AWS Bedrock) there JSON templates and Java files (one JSON, on hybrid JSON and a JAVA file). But in the web modeler there is only one template when I try to use them. Do I need to adjust all of them or are some of them generated?

[johnBgood]

@philippfromme If there are Java files, then the JSON will be generated. But only in our repo. The web modeler part needs to be updated manually :/

So yea, in this example you need to update:

• The Java files + then generate the JSON templates using mvn clean install -DskipTests
• The web modeler part

[philippfromme]

The web modeler part

But this going to change soon if I'm not mistaken. For now I'll focus on the PR and we'll take it from there.

[johnBgood]

But this going to change soon if I'm not mistaken

True :)