Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update template descriptions and add keywords to improve refactorings suggestions #3089

Open
philippfromme opened this issue Aug 14, 2024 · 14 comments · May be fixed by #3466
Open

Update template descriptions and add keywords to improve refactorings suggestions #3089

philippfromme opened this issue Aug 14, 2024 · 14 comments · May be fixed by #3466
Labels
kind:task Categorizes an issue or PR as general maintenance, i.e. cleanup, refactoring, etc.

Comments

@philippfromme
Copy link

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.

image

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 bpmn-io/refactorings#27

@philippfromme philippfromme added the kind:task Categorizes an issue or PR as general maintenance, i.e. cleanup, refactoring, etc. label Aug 14, 2024
@philippfromme
Copy link
Author

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

@YanaSegal
Copy link

@philippfromme depends where:

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

@philippfromme
Copy link
Author

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
Copy link

The template creator is responsible for providing the description.

@crobbins215
Copy link

@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
Copy link
Contributor

@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
Copy link
Author

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:

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
Copy link
Contributor

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
Copy link
Author

@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
Copy link
Author

@johnBgood Would it look something like this?

@johnBgood
Copy link
Contributor

@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
Copy link
Author

@johnBgood Thanks for helping out with that!

@philippfromme philippfromme linked a pull request Oct 10, 2024 that will close this issue
1 task
@philippfromme
Copy link
Author

@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
Copy link
Contributor

@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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
kind:task Categorizes an issue or PR as general maintenance, i.e. cleanup, refactoring, etc.
Projects
None yet
Development

Successfully merging a pull request may close this issue.

4 participants