C# zeebe client methods

Hi guys, I’m working with the c# client and some questions arrived…

  • could you help me describing each method?
    I can’t understand what is the purpose of each one, except for the JobType and Handler.

_zeebeClient.NewWorker()
.JobType(“Worker_t1”)
.Handler((c, j) =>
{
c.NewCompleteJobCommand(j.Key).Send();
})
.MaxJobsActive(1)
.Name(Environment.MachineName)
.PollInterval(TimeSpan.FromSeconds(1))
.Timeout(TimeSpan.FromMinutes(60))
.Open();

  • As I understand the TopologyRequest() is required when a cluster is deployed… but I supposed that Zeebe manages the nodes by itself

  • What is the purpose of the NewActivateJobsCommand(); command?

Thanks

Can you please format the code snippets with the correct markup ? using (triple backquotes blocks) like this:

<your code here>

Regarding your first question:

.JobType(“Worker_t1”)
.Handler((c, j) =>
{
c.NewCompleteJobCommand(j.Key).Send();
})

You are creating a new Job Handler for the type Worker_t1 that means that in you process definition you will have a service task with JobType Worker_t1 and every time that the service task is executed a new Job from type Worker_t1 will be created. The Handler is the code that needs to be executed each time that any of your workflow instances hit the service task. By calling c.NewCompleteJobCommand(j.Key).Send(); the process will move forward… that means that before that line you should have the logic that you want to execute as part of your Service Task (for example calling another service or doing some calculations)

Hope this helps.

Thanks for the answer.

What I mean is… the only 2 methods that I understand are those JobType and Handler

I don’t understand the purpose of the following methods:

.MaxJobsActive(1)
.Name(Environment.MachineName)
.PollInterval(TimeSpan.FromSeconds(1))
.Timeout(TimeSpan.FromMinutes(60))
.Open()

and

TopologyRequest()

and

NewActivateJobsCommand()

those are just configuration parameters for how to fetch the jobs and how to process them.

the other two are more internal, (have you check the docs? )

  • TopologyRequest() sounds to get the share of the cluster (how many brokers are and how many partitions, and who is the leader/follower of each partition) Zeebe | Camunda 8 Docs
  • NewActivateJobsCommand() sounds to notify the cluster to create a new job from a certain type. Zeebe | Camunda 8 Docs
1 Like

NewActivateJobsCommand() sends a command to the Gateway to send back any available jobs for the worker.

MaxJobsActive() is how many jobs this worker can handle in parallel. If there are 100 jobs of this task type and you specify a value of 5 for this, then the gateway will send back 5 jobs. You have to complete some jobs (or they time out) to get back more on subsequent calls.

Name is the id to use for the worker in logging.

PollInterval is how often the worker will ask for jobs.

Timeout is how long the broker should wait for a response before giving any allocated job to another worker request.

3 Likes

For all interfaces and methods exist documentation for example for the IJobWorkerBuilderStep1.cs

//
//    Copyright (c) 2018 camunda services GmbH (info@camunda.com)
//
//    Licensed under the Apache License, Version 2.0 (the "License");
//    you may not use this file except in compliance with the License.
//    You may obtain a copy of the License at
//
//        http://www.apache.org/licenses/LICENSE-2.0
//
//    Unless required by applicable law or agreed to in writing, software
//    distributed under the License is distributed on an "AS IS" BASIS,
//    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
//    See the License for the specific language governing permissions and
//    limitations under the License.
using System;
using System.Collections.Generic;
using Zeebe.Client.Api.Responses;

namespace Zeebe.Client.Api.Worker
{
    public interface IJobWorkerBuilderStep1
    {
        /// <summary>
        /// Set the type of jobs to work on.
        /// </summary>
        /// <param name="type">the type of jobs (e.g. "payment")</param>
        /// <returns>the builder for this worker</returns>
        IJobWorkerBuilderStep2 JobType(string type);
    }

    /// <summary>
    /// The job handler which contains the business logic.
    /// </summary>
    /// <param name="client">the job client to complete or fail the job</param>
    /// <param name="activatedJob">the job, which was activated by the worker</param>
    public delegate void JobHandler(IJobClient client, IJob activatedJob);

    public interface IJobWorkerBuilderStep2
    {
        /// <summary>
        /// Set the handler to process the jobs. At the end of the processing, the handler should
        /// complete the job or mark it as failed;
        ///
        /// <p>Example JobHandler implementation:
        ///
        /// <pre>
        /// var handler = (client, job) =>
        ///   {
        ///     String json = job.Variables;
        ///     // modify variables
        ///
        ///     client
        ///      .CompleteCommand(job.Key)
        ///      .Variables(json)
        ///      .Send();
        ///   };
        /// </pre>
        ///
        /// The handler must be thread-safe.
        /// </summary>
        /// <param name="handler">the handle to process the jobs</param>
        /// <returns>the builder for this worker</returns>
        IJobWorkerBuilderStep3 Handler(JobHandler handler);
    }

    public interface IJobWorkerBuilderStep3
    {
        /// <summary>
        /// Set the time for how long a job is exclusively assigned for this worker.
        ///
        /// <p>In this time, the job can not be assigned by other workers to ensure that only one worker
        /// work on the job. When the time is over then the job can be assigned again by this or other
        /// worker if it's not completed yet.
        ///
        /// <param name="timeout">the time as time span (e.g. "TimeSpan.FromMinutes(10)")</param>
        /// <returns>the builder for this worker
        /// </summary>
        IJobWorkerBuilderStep3 Timeout(TimeSpan timeout);

        /// <summary>
        /// Set the name of the worker owner.
        ///
        /// <p>This name is used to identify the worker to which a job is exclusively assigned to.
        ///
        /// </summary>
        /// <param name="workerName">the name of the worker (e.g. "payment-service")</param>
        /// <returns>the builder for this worker</returns>
        IJobWorkerBuilderStep3 Name(string workerName);

        /// <summary>
        /// Set the maximum number of jobs which will be exclusively activated for this worker at the same
        /// time.
        ///
        ///<p>This is used to control the back pressure of the worker. When the maximum is reached then
        /// the worker will stop activating new jobs in order to not overwhelm the client and give other
        /// workers the chance to work on the jobs. The worker will try to activate new jobs again when
        /// jobs are completed (or marked as failed).
        ///
        /// <p>Considerations:
        ///
        /// <ul>
        ///   <li>A greater value can avoid situations in which the client waits idle for the broker to
        ///       provide more jobs. This can improve the worker's throughput.
        ///   <li>The memory used by the worker is linear with respect to this value.
        ///   <li>The job's timeout starts to run down as soon as the broker pushes the job. Keep in mind
        ///       that the following must hold to ensure fluent job handling: <code>
        ///       time spent in buffer + time job handler needs until job completion < job timeout</code>
        /// </summary>
        /// <param name="maxJobsActive">the maximum jobs active by this worker</param>
        /// <returns>the builder for this worker</returns>
        IJobWorkerBuilderStep3 MaxJobsActive(int maxJobsActive);

        /// <summary>
        /// Set a list of variable names which should be fetch on job activation.
        ///
        /// <p>The jobs which are activated by this command will only contain variables from this list.
        ///
        /// <p>This can be used to limit the number of variables of the activated jobs.
        /// </summary>
        /// <param name="fetchVariables">list of variables names to fetch on activation</param>
        /// <returns>the builder for this worker</returns>
        IJobWorkerBuilderStep3 FetchVariables(IList<string> fetchVariables);

        /// <summary>
        /// Set a list of variable names which should be fetch on job activation.
        ///
        /// <p>The jobs which are activated by this command will only contain variables from this list.
        ///
        /// <p>This can be used to limit the number of variables of the activated jobs.
        /// </summary>
        /// <param name="fetchVariables">list of variables names to fetch on activation</param>
        /// <returns>the builder for this worker</returns>
        IJobWorkerBuilderStep3 FetchVariables(params string[] fetchVariables);

        /// <summary>
        /// Set the maximal interval between polling for new jobs.
        ///
        /// <p>A job worker will automatically try to always activate new jobs after completing jobs. If
        /// no jobs can be activated after completing the worker will periodically poll for new jobs.
        ///
        /// </summary>
        /// <param name="pollInterval">the maximal interval to check for new jobs</param>
        /// <returns>the builder for this worker</returns>
        IJobWorkerBuilderStep3 PollInterval(TimeSpan pollInterval);

        /// <summary>
        /// Set the polling timeout for the job activation.
        ///
        /// <p>The activate jobs request will be completed when at least one job is activated or after the given requestTimeout.
        ///
        /// </summary>
        /// <param name="pollingTimeout">the polling timeout (e.g. "TimeSpan.FromMinutes(10)")
        /// </param>
        /// <returns>the builder for this worker</returns>
        IJobWorkerBuilderStep3 PollingTimeout(TimeSpan pollingTimeout);

        /// <summary>
        /// Enables job worker auto completion.
        ///
        /// <p>
        /// This means if the user does not complete or fails the activated job by himself
        /// then the worker will do it.
        ///
        /// </summary>
        /// <returns>the builder for this worker</returns>
        IJobWorkerBuilderStep3 AutoCompletion();

        /// <summary>
        /// Open the worker and start to work on available tasks.
        /// </summary>
        /// <returns>the worker</returns>
        IJobWorker Open();
    }
}
2 Likes

The autogenerated docs for the JavaScript client are a useful reference: https://creditsenseau.github.io/zeebe-client-node-js/

Can you do the same thing for C#? Maybe this https://github.com/dotnet/docfx

2 Likes

API documentation is now available under https://zeebe-io.github.io/zeebe-client-csharp/index.html

2 Likes