Add OfficeToPdf connector

[pierre-yves-monnet]

Hello @camunda-community-hub/devrel, here a new PR for this documentation page

[berndruecker]

@pierre-yves-monnet Might be worth to check the difference between a connector and a worker, see also https://camunda.com/blog/2022/10/camundacon-2022-qa-bernd-daniel/ -->

What is the difference between a Job Worker and a Connector?

The difference is actually not too big. Especially the code is pretty similar. But the connector works on a slightly higher abstraction. For example, you cannot simply access all process variables, but need to explicitly define what data will be available. Additionally, you will have support to handle secrets properly, which you have to handle on your own in a Job Worker.

This reduces the scope of what a connector can do, which allows us to build different runtimes. So while in Spring Boot the difference is hard to see, you can run a connector function in SaaS in a stateless Google Function, which is not the case for a Job Worker.

Anyway, I expect that we will add some more syntactic sugar on connectors over time, so this might even get the default way of waiting Java glue code in future, making it unnecessary to leverage the “low level” Job Worker API. But honestly, this also depends on how the community is picking things up.

And I just recognized, I forgot to talk about element templates there 😨

[pierre-yves-monnet]

Hello, Thank you for your comment. If I want to move this code to a pure Connector, what is the path then?

I understand (correct me if I'm wrong)

1/ one repository per connector (or can we group multiple connectors in the same repository?)

2/ the code should be purely "extends AbstractConnector"

3/ using the https://github.com/camunda-community-hub/community-action-maven-release, I will create a release and push it to the Maven Central.

4/ @berndruecker: the element template is generated by the Cherry Framework. I can save it in the repository (under an "element-template" path?).

[berndruecker]

Great questions - we haven't yet settled on the exact answers to your question.

1. I tend to say, 1 repo per connector is easiest for now (even if i could imagine that it changes to a dedicated directory for a connector). I am not yet sure if and how we want to support one code base defining multiple connectors.

2. The code must define a function: https://github.com/camunda/connector-sdk#create-a-connector

@OutboundConnector(
    name = "PING",
    inputVariables = {"caller"},
    type = "io.camunda.example.PingConnector:1"
)
public class PingConnector implements OutboundConnectorFunction {

3. Not sure if that is a requirement, but it definitely would make things easier if people want to use it - so I would at least consider it a best practice.

4. An element-template must be in a directory element-template. How it ends up there does not matter too much for the moment (I understand that you auto-generate it on the fly - still I would like to start with that - as it is easy)

So as you can see, we are pretty early - but I appreciate that you bring up the right questions :-)

@tmetzke: Maybe we should move that an issue to define some guardrails for the moment?

[tmetzke]

Hi @pierre-yves-monnet, good questions indeed 👍

I agree with what Bernd added here so far.

Regarding 2/, one Connector is ideally implementing the OutboundConnectorFunction interface, yes. Have a look at our template as well for reference.

Regarding 3/, we currently offer two ways of consuming our out-of-the-box Connectors:

1. An uber JAR that contains all necessary dependencies of the Connector.
2. A regular thin JAR that only contains the Connector's code.

The uber JAR can easily be added to Docker images or the pre-packaged runtime. The thin JAR can easily be added as a Maven/Gradle dependency and be used in Spring Zeebe, for example.

Regarding 4/, we also provide the element template with a GitHub release of every Connector. That way, it's easy to see for users which element template is associated with which release of your Connector behavior.

I agree that we should create some guidelines on this, @berndruecker 👍

[pierre-yves-monnet]

Hello, Great, I will see how to move these objects to connectors. In the first move, I will use the same GitHub: these if 10 connectors for the moment CMIS collection will add 8 more.

Is that acceptable that the connector implements OutboundConnectorFunction AND extends a class? For the Cherry dashboard, we want the developer to give more information on input/ output in order to generate the template modeler and display information to the administrator and designer (https://github.com/camunda-community-hub/zeebe-cherry-framework). Our target is to be 100% compliant with the Connector framework and adds more information.

PS: Actually, all connector extends AbstrraceConnector, which implement OutboundConnectorFunction , but we can move the implementation one level up.

public abstract class AbstractConnector extends AbstractRunner implements OutboundConnectorFunction {

[tmetzke]

Hi @pierre-yves-monnet, excited to see those transformations taking place. Thanks for putting in the effort here 👍

As far as I can see, it should be enough that the Connector functions technically implement the interface. We use a ServiceLoader to load all classes that implement the interface, which should work regardless of intermediate classes in the hierarchy.

[pierre-yves-monnet]

Hello,

To follow your direction, I do the job for one connector. If you are OK with this contribution, I will do the same job for the other connectors. Each connector will have its GitHub repository.

1/ I created one repository per connector. The first contribution is the SendBPMNMessage (https://github.com/camunda-community-hub/camunda-8-connector-sendBPMNmessage)

2/ This connector implements the interface OutboundConnectorFunction public class SendBPMNMessageFunction extends AbstractConnector implements OutboundConnectorFunction {

It extends the AbstractConnector from the Cherry Framework to get all advantages on this framework. If you don't like this, I can go one step ahead, keep this class without the extension, and creates a class in the Cherry Collection that extends this one - but this means more work)

3/ You will find a folder element-templates with the element templates.

Thank you for your review,

[tmetzke]

Thanks, @pierre-yves-monnet, for adjusting this 👍 I will give your project a closer look as soon as I can (probably tomorrow, we just had a release to finish). In the meantime, just wanted to check with you, are you certain about the lifecycle banner stable? If you're OK with the guarantees and expectations users have with this, that's OK, just wanted to make sure this was intentional. 🙂

[berndruecker]

Lifecycle badges are explained here: https://github.com/Camunda-Community-Hub/community/blob/main/extension-lifecycle.md. I would spontaneously see this as POC or Incubating

[tmetzke]

Hi @pierre-yves-monnet, thanks again for adjusting your Connector 👍 There are a couple of things to look at and discuss, probably.

Included runtime environments

A Connector should come without any runtime environment since it is supposed to be environment-agnostic. Your code however comes with Spring Zeebe and the zeebe-cherry-framework, which in turn brings along the Zeebe Java client as well as the Connector Runtime 0.2.x.

Why is this an issue? If someone wants to embed your Connector in Spring Zeebe or any other runtime environment (either as a Maven dependency or as a fat JAR including dependencies) this will become an issue. There will be multiple runtimes available that can execute Connectors which will most probably lead to conflicts.

What can you do about it? Remove all runtime-related dependencies.

Spring Zeebe can simply be removed, as people can use Spring Zeebe directly to execute Connectors (see documentation). No need to include it in your project, I believe.

The cherry framework dependency could be a bit more tricky. I don't have much knowledge about it, but it seems to bring along a runtime (Connector Runtime 0.2.x) - this is counterproductive. Either you can remove the dependency completely or create different artifacts in that framework, one of them covering the basics you need here in a Connector without bringing along a runtime.

Please also try to avoid adjusting versions of something like the Jakarta Validation API, since this is determined by the SDK's connector-validation module and can lead to version conflicts quite quickly when people use your Connector together with other Connectors that use that module as well.

SDK version 0.2.x

Please try to move to Connector SDK 0.3.0. Have a look at the updated Connector template repository for inspiration. The POM in the repository also contains the capabilities to build a fat JAR automatically. and also the Update Guide.

Let me know what you think.

[tmetzke]

Something I noticed just now:

• You are using Spring to inject a ZeebeContainer for example (also the main function is annotated as @Component). This makes the Connector less reusable since it can only work in Spring environments. However, not all Connector runtimes will be in that realm. So, I would urge you to remove Spring-related stuff from the Connector.
• Connectors don't throw ZeebeBpmnErrors, they throw technical errors and can provide error code with them. This is new in Connector SDK 0.3.0, you can read about it in the example over at https://docs.camunda.io/docs/next/components/connectors/custom-built-connectors/connector-sdk/#runtime-logic.

[pierre-yves-monnet]

Hello, Connector SendBPMNMessage comes too early because it needs to have a ZeebeClient, which is not available in the ConnectorSDK at this moment.

So, I focus on the first connector from the Office Collection, and I choose the OfficeToPdf connector. Thank you for reviewing it. Best

[tmetzke]

Hello, Connector SendBPMNMessage comes too early because it needs to have a ZeebeClient, which is not available in the ConnectorSDK at this moment.

As mentioned in the SDK issue, a Connector should not rely on the Zeebe client being available. If you want to connect to a C8 cluster, create a Zeebe client in your Connector as you would with creating a client to any other external system.

[igpetrov]

Hi @pierre-yves-monnet,

Thank you for your contribution.

Few thoughts on reviewing the suggested connector:

• Could you please declare the license?
• Could you please add an instruction for the users on how to use it?
• I noticed that you're trying to publish your connector but it won't pass. Is it something on your radar?

Thank you.

[pierre-yves-monnet]

Hello @igpetrov

Could you please declare the license? ==> Done.

Could you please add an instruction for the users on how to use it? ==> I add them in the README. I hope this is clear. I noticed that you're trying to publish your connector, but it won't pass. Is it something on your radar? ==> Yes, I got some issue understanding what was missing, but now it's good; publication is OK.