Workflows: how to read the body of an incoming request or use a custom controller

[MarGraz]

Hi Everyone,

I'm working with workflows, but I'm new to using them in Orchard Core, so I'm trying to understand what's the best way to implement my requirements 🤓

Basically, I need to:

1. Receive a POST request (I already set up an HTTP Request event for this);
2. Read the body of the request and create a Content Item (using a specific Content Type);
3. From the previous body read, get the value of the custom PublisherId field;
4. Use the PublisherId to query the DB and get the related Publisher Content Item (that already exists), which contains an email address;
5. Use the email address to send an email (I saw that there is a Send Email task).

For me it is not clear how to do this by looking at the documentation available here, previous discussions (there are few of them), and also watching few YouTube videos 😶‍🌫️

My questions are:

• How can I read the payload of a POST HTTP Request event in a workflow?
• May I need to use a custom Controller to manipulate data and query the DB?
• If a controller is needed, to use it from the workflow do I need to use the Filter Incoming HTTP Request event, instead of the HTTP Request event? If yes, how can I get the body once inside my controller?
• Is there documentation/examples that explain how to manage these use cases using the workflow panel?

Thank you

[Piedone]

Generally, I recommend you use Workflows if >=1 of the below criteria are valid for your use case:

• You can't write code (either because you're not a developer or you're working within a restricted SaaS).
• You want all or at least most pieces of the logic to be admin-confgurable (e.g., you want admins to frequently change the e-mail's text).
• What Workflows provides out of the box at least almost matches your requirements.

In any other case, I'd write code. For handling requests, I'd write code too (what you describe looks better suited for an ApiController, or perhaps minimal API endpoint, than an MVC controller).

You can also mix and match: e.g., if you have some complex logic that in the end sends an e-mail, so you want to code the complex logic but still want to let people modify the e-mail text frequently, then you can create a custom Workflows Activity. So, your complex custom logic will be a single box in a workflow, that you can hook up to an Email Task as usual (or alternatively, you could also create your custom editor for the e-mail text, like with site settings or Custom Settings).

[MarGraz]

@Piedone thank you for your reply.

Yes, we are considering the points you mentioned. Our goal is to give the admin the ability to configure various options. Because of this, we are exploring how to combine workflows with custom controllers.

As you said, we will mix and match these components, as we need to send an email to our user in the end and make it configurable.

To achieve this, we are trying to understand:

1. How to read a payload within the workflows (we are curious to explore this);
2. How to use a custom controller in combination with workflows.

We couldn't find a reference guide that explains this basic usage, which is why we started this discussion.

Thank you

[Piedone]

1. Apart from the answer below, in your custom Task, you can use IHttpContextAccessor as usual, just as HttpResponseTask does (how it's accessible under a URL is not via a controller BTW, but via special routes; if you want to check this out, start from WorkflowRoutesHandler).
2. Since you'd use a controller to start a workflow, that's probably the least typical usage of Workflows, but doable. You'd need to start the WF from your controller, similar to what e.g. WorkflowActionFilter does.

Also, if you found something missing in the docs, it would be great if you could submit a PR for fixes; I can again review them if you ping me.

[MarGraz]

Thank you for your reply 😊

1. Ok, I saw that WorkflowRoutesHandler implements WorkflowHandlerBase, so it's a different approach compared to what's explained here with IActivity, right?
2. Yes, the idea is to trigger an ApiController, do some business logic, and then end in the workflow (through a webhook or similar). Ok, so the example to follow could be WorkflowActionFilter.

Yes, I will definitely work on the documentation. I'm quite busy now, but I want to improve it because I'm learning from scratch, and I see many areas where we can enhance the documentation (I've already done PRs for this).

Thank you

[douwinga]

We trigger workflows quite a bit in code. We just use signals for that and trigger them like so:

await _workflowManager.TriggerEventAsync("SignalEvent", new Dictionary<string, object>
{
    {"Signal", "SomeActionHappened"},
    {"ContentItem", contentItem}
});

This makes it simple to trigger a workflow for anything from anywhere without needing a custom workflow event. We actually used this from an api endpoint this week to handle an issue with a webhook from a service we do not control that could not handle the Http Request Event because the token was too long. Not necessarily ideal, but it worked for our needs. We do a lot of workflows because we have a lot of tenants that have requirements that only affect the single tenant, so we try to keep that out of code as much as possible. We keep the core functionality in code that allows our power users to configure things the way they need to for their specific tenants and workflows is a big piece to enabling that.

[Piedone]

Re 1.: I just mean that the WF module itself allows workflows to start from an URL not via a controller, but by registering workflows for routes with WorkflowRoutesHandler. This is just FYI, you don't need to worry about it unless you want to work on the internals of the module.

[douwinga]

What should work for you unless I am missing something is to use a "Http Request Event" as the startup task of your workflow. Then use a "Set Property Task" to deserialize the request data by setting the Value to deserializeRequestData();

Then you should have access to the request properties in your workflow context (liquid: {{ Workflow.Properties["RequestData"] }}).

[MarGraz]

@douwinga thank you so much for your reply.

I will try it out. I saw the Http Request Event, but it was not clear to me that in the Value input field of the Set Property Task, I can call JavaScript functions from this list. You opened up a new world for me 😅

I will try it and let you know.

@Piedone I think we should update the documentation, and we should also modify the description at the bottom of the input field of Set Property Task, to add the link to the functions list.
Currently "The value to store in the specified property", sounds like I need to fill it with a static value that will be passed in the request (that doesn't have any sense, I know).

Thank you

[MarGraz]

@douwinga I did some tests, but I'm not able to create a Content Item using the workflow 🤕
I'm trying to do something really basic, however, create a Content Item from a webhook following these steps:

1. I added an Event Http Request, in POST, to be called as a webhook that has a JSON in the body (of course, it will not be public, but called by an internal process 😜);
2. I added a Set Property Task with the deserializeRequestData(); value to deserialize the JSON payload (as you explained here);
3. I added a Create Content Task of type BookstoreAddPurchaseTermsRequest that I defined in Orchard Core. This type is only made up of TextField, as you can see from the screenshot below. In the Value I tried to assign values using JSON + Linq as you can see below too;
4. I added a "Fail" or "Success" Notify Task from which I can see in the Output debug of Visual Studio if the operation succeeded or not.

Of course the operation never succeeds 🤔🤌
Here is my workflow in a screenshot:

Here is the payload I'm trying to pass to the POST Http Request, where I added a RequestData property:

{
    "RequestData": {
        "FromBookStoreName": "test1",
        "FromBookStoreId": "test2",
        "FromBookStoreUserId": "test3",
        "ToPublisherManagerName": "test4",
        "ToPublisherManagerId": "test5",
        "ToPublisherManagerUserId": "test6",
        "AddToPurchaseTermsId": "test7"
    }
}

Here is the JSON + Liquid I added in the Create Content Task Value field:

{
  "FromBookStoreName": "{{ Workflow.Properties["RequestData"].FromBookStoreName }}",
  "FromBookStoreId": "{{ Workflow.Properties["RequestData"].FromBookStoreId }}",
  "FromBookStoreUserId": "{{ Workflow.Properties["RequestData"].FromBookStoreUserId }}",
  "ToPublisherManagerName": "{{ Workflow.Properties["RequestData"].ToPublisherManagerName }}",
  "ToPublisherManagerId": "{{ Workflow.Properties["RequestData"].ToPublisherManagerId }}",
  "ToPublisherManagerUserId": "{{ Workflow.Properties["RequestData"].ToPublisherManagerUserId }}",
  "AddToPurchaseTermsId": "{{ Workflow.Properties["RequestData"].AddToPurchaseTermsId }}"
}

Here is the BookstoreAddPurchaseTermsRequest content type I defined in Orchard Core:

Any ideas?

Thank you

[douwinga]

Your create content JSON does not look correct. The easiest way to determine the correct JSON is to look at an existing content item's JSON by going to the Content Items list and find an existing item and then click Actions and "View as JSON"

Note: There are some other buttons in this screenshot that do not exist in OrchardCore and are custom (Console and Edit as JSON)

You will need this feature enabled to do this:

Also, check your workflow instances to help with debugging as you can get the entire state of the workflow instance

[MarGraz]

@douwinga thank you for your suggestions.

Yes, finally it works 🥳

• Installing the feature View Or Download Content As JSON, which adds the View as JSON option on created items, helped a lot in determining the correct JSON. Before, I was looking into the database 😅
• After every run, it's also good to check for errors by looking into the run Instances. Sometimes, the last instance might not appear immediately and could show up after 1 or 2 minutes. This delay is normal because the process is asynchronous.

What have I done?

Here is a screenshot of the entire workflow:

1. I created an Event HTTP Request, in POST as a webhook, to be called from Postman. I set it as a Startup task from the "Power button" after adding the task (it turns green if set up as a "startup task"):

2. I added a Task Set Property:

3. I created a Task Create Content:

4. I added a Task Send Email:

5. From Postman, I called the URI available in the HTTP Request.

Note: this URI is public and not protected by OAuth 2, so it's better to call it from an internal process.

I hope this can help other users.
@Piedone I will create a guide about this soon, as it's currently missing.

Thank you

[MarGraz]

@douwinga do you know if it is possible to create a workflow that accepts a payload to send an email, without creating an Orchard Core Content Item?

In this case, I created the BookstoreAddPurchaseTermsRequest Content Type, and in the workflow his instance, but how can I send an email that reads values from a payload without creating a Content Item?

Thank you

[douwinga]

I am confused on your question. In your "Edit Email Task" screenshot it looks like you are already outputting the payload in the email (although I am not sure why you are adding JSON to the body as that should just be the body of the email using html). So just remove the task where you are creating the content item. Or are you talking about retrieving an existing content item instead of creating one?

[MarGraz]

I was talking about using the payload shown in the Postman screenshot here, and using it directly in the Send Email Task.

I think you already answered my question in your last response. I believe it is sufficient to remove the Content Item creation and intercept the JSON payload directly in the Send Email Task.

Thank you