This guide describes how to design ActiveVOS workflows that leverage the new queue based communication mode between P360 and ActiveVOS

Prerequisites

See the Installation Manual for installation of ActiveVOS with ActiveMQ support and configuration of queues in ActiveVOS
(Note: ActiveVOS version 9.2.4.6 is a prerequisite for queue based interactions between P360 and ActiveVOS)

See the Message Queue API documentation
- how to generally configure queues in P360 server
- message headers and payloads for the various interactions between Product 360 and ActiveVOS

REST versus JMS based workflows

At its core, ActiveVOS is based on SOAP Style web services backed by WSDL definitions. The support for both REST based web services and for JMS interactions are internally mapped onto these concepts. The details are slightly different and they have an impact on how interactions work with Product 360 and workflows.

Area	REST based communication	Queue based communication
Service interface definitions	Leverages built-in generic REST service interface definitions.	Interface definitions need to be added as a WSDL in the ActiveVOS project.
Message header	Full access to REST headers through the built in interface definition.	Access to JMS header fields is available through "Partner" variables.
Message body	Free choice of format, can be JSON.	Message body needs to adhere to WSDL and therefore restricted to XML.
Incoming messages	Usually paired with an outgoing message to implement the HTTP response.	One way, there is no need to send a response message to the queue. P360 regards the message as successfully delivered as soon as it has been placed into the queue.
Outgoing messages	Outgoing messages may be "one-way" or paired with incoming messages that contain the response for the outgoing request,	Outgoing messages are written to a queue. Similarly to the REST case this may be paired with an incoming message for the response which also comes in via a queue. However from a workflow designer perspective they can be seen as two "one-way" communications.
Special case of outgoing message: Workflow tasks definition	Body can be either JSON or XML. Workflow task definitions include ActiveVOS workflow endpoints that have to be invoked via REST.	Body has to be XML. Workflow task definitions set the communication mode to "QUEUE", include the queue ID (as defined in P360 configuration) and the workflow endpoints to be invoked via JMS.

Mandatory Permission Required For Queue Based Communication

For BPM to have queue based communication with P360, "Queue Communication" named Action rights is required for the user group of the user used in BPM workflows. Without having this action right for the user group, BPM will get Unauthenticated error when it try to contact Product 360 via message queue.

images/download/attachments/506623503/image2020-8-21_14-24-4.png

Types of interactions and their representation in the WSDL file

There are a couple of different message types that can be received from/sent to P360:

Incoming event triggers
Outgoing Service API requests (one-way or request-response)
Incoming responses for Service API requests (result or error responses)
Outgoing DQ execution requests
Incoming responses for DQ executions (result or error responses)

To avoid the overhead of defining each of these messages down to the smallest detail within the WSDL file (or a separate XML Schema file) all of the messages have been defined to have anyType content within some root tag. The approach is different between incoming and outgoing messages:

For incoming messages we can use a single type with an arbitrarily defined root tag as ActiveVOS is not strictly checking the root tag.
For outgoing messages the defined root tag is what gets sent to P360 and needs to match P360 expectations. Therefore there are a number of message types defined with different root tags.

Based on these messages several port types have been defined:

Port type	Operation	Input message type	Remarks
Receive	`receive`	`p360RoutedMessage`	This message type has two parts: `p360Header`: this part for now only contains an optional element `correlationId` `p360MessageBody`: this part contains the original message sent from P360 (with an adjusted root tag)
Send	`callWithoutParameters`	`emptyMessage`	Used for sending requests to P360 that do not require any input parameters. Due to WSDL restrictions the operation still needs to specify a message type.
	`startWorkflow`	`startWorkflowMessage`	This operation and the following ones are used for requests that require different types of input messages.
	`enterWorkflowStatus`	`enterWorkflowStatusMessage`
	`leaveWorkflowStatus`	`leaveWorkflowStatusMessage`
	`executeQualityProfile`	`dataQualityProfileMessage`
	`listWrite`	`entityItemTableMessage`
Router	route	`p360Message`	Only used by the P360Router process - see next section.

Router process

In the REST based communication mode P360 invokes the exposed REST endpoint of the respective ActiveVOS process directly. In the queue based communication mode all P360 requests go to a single queue.

To deal with this a router process is set up on ActiveVOS which has essentially three responsibilities;

Evaluate the JMS header property P360TargetService that is used to forward the request to the right endpoint.
Copying the request message into a common base format (p360RoutedMessage) that all endpoints can deal with.
Adding the correlation ID to the common base format message (see below for details).

When ActiveVOS monitors a queue for incoming messages it supports reading the target endpoint from the JMS header property JmsTargetService . However this feature does not work with endpoints that are based on anyType messages.

Core orchestration project

As described above, both the WSDL and the P360Router process are key components for setting up queue based communication between P360 and ActiveVOS. Therefore a ready-to-use orchestration project is made available as a ZIP file. It contains the WSDL and the BPEL and PDD files for the P360Router. Import this project into your ActiveVOS Designer workspace. While you can then add your workflow process definitions simply to this project, it is recommended to set them up separately:

Create one or more separate projects for your workflow processes.
Add the P360_JMS_Core project as a project reference in your project(s).
Use the message, port and partner link types of the WSDL when defining variables and participants in your processes.
The WSDL also includes a correlation definition that can be used in the correlation set definitions of your workflow processes (see below).

The P360_JMS_Core project needs to be deployed to your ActiveVOS as a prerequisite for the deployment of your own workflows. Before doing so note the endpoint name of the "Consumer" participant of the P360Router process in the PDD file. This name needs to match the default service set of the queue listener set up in the ActiveVOS Message Service configuration. By default both are called P360RouterService.

The listener monitors the queue which P360 uses to send requests to ActiveVOS. These messages need to flow through the P360Router process before they are forwarded to the actual target endpoint.

The core orchestration project is included as a ZIP file in the BPM accelerator package.

Correlation

The correlation concept assures that incoming messages are routed to the right process instance of a workflow. A good starting point is to use the process ID for this, however for more complex workflows with parallel execution it may be necessary to add additional information to the correlation IDs of specific endpoints within the workflow.

ActiveVOS sets the correlation ID by picking it from a defined path of an outgoing message. It then checks a defined path in incoming messages to map the request to an existing process instance. For this to work the correlation ID must be part of both message bodies.

For backwards compatibility reasons many P360 calls expect the correlation ID to be sent in the processId field of a request and also return it in the same way in subsequent requests to ActiveVOS. Newer APIs however support the use of the JMSCorrelationID header.

On the receiving side the P360Router process takes care of picking the correlation ID from the right location and puts it into the p360Header part of the p360RoutedMessage. So the individual workflows can define their correlation ID settings based on this without worrying how it was transmitted.

Unfortunately on the outgoing side these details cannot be hidden. Best practice here is to:

Write the correlation ID to the JMSCorrelationID header of the outgoing message. This is where P360 expects it in general.
Write it to a top level element called processId in the outgoing message body. This is for ActiveVOS correlation definition to be able to pick it up on the way out.
Note that the name processId is used for backwards consistency. This is where the correlation ID is already passed in the REST based communication use case.

Defining participants

Consumers

Configure the Consumer participants in your workflow processes as follows

Select p360ReceivePortType as its service interface.
Select p360ReceivePLT as its partner link type
Add a receive activity to your workflow, select the newly created Consumer, select the receive operation and use a variable of type p360RoutedMessage to store the input.
After creating the deployment descriptor for your workflow set "Binding" to "Document literal" and the name of the endpoint to how it should be addressable from P360.

Note that such a Consumer is always expecting incoming messages at its defined endpoint. So usually you cannot reuse the same Consumer at different points in your workflow.

Producers

Configure a Producer participant as follows:

Select p360SendPortType as its service interface.
Select p360SendPLT as its partner link type
After creating the deployment descriptor for your workflow set the Producer to be a "JMS Service" and "dynamic"
Prepare the an input variable and the Producer in a script activity of your workflow
- Setup a variable of the right type for the desired operation's input message body.
- Setup the message header by assigning an appropriate XML structure to your newly created "Partner" (Choose "Partner" and your new participant as the target of a copy).
  See section below on how to create this "appropriate XML".
- Add an invoke activity to your workflow, select the newly created participant, the desired operation and the variable as its input.

Note that with the "dynamic" setting the same Provider can be used for any outgoing calls from the workflow to P360. You just need to prepare the header and the input variable upfront.
In case of parallel execution threads you should still use separate Provider participants.

Setting up the outgoing message header

Add a script activity to your workflow
Add a copy assignment to the script activity
- On the source side select "Expression" and set it to XQuery based expressions.
- On the target side select "Partner" and the newly created Producer
Go back to the PDD file and temporarily select "static" for the Producer. This will populate the text box below with an XML template. Copy this for further use.

Go back to the copy assignment and paste the copied XML as the starting point for the expression. You need to make the following adjustments:

Section	Value
`address`	The address needs to be set to the name of the target queue. Note that is needs to be the JNDI name configured for the queue on the ActiveVOS server side - not the actual queue name on the JMS server. The are two distinct queues that can be used here at the moment: one for DQ executions and one for Service API requests.
`jmsManagerId`	The jmsManagerId needs to match the name of the "Message Service" configuration in the ActiveVOS server.
`jmsMessageFormat` `jmsMessageType`	Leave these at "xml", "text" respectively.
`jmsTTL`	Set to "0" for most cases to avoid message expiration. Sometimes messages can become obsolete if they haven't been dealt with in a defined time frame. In such cases you can set this to the maximum number of milliseconds that this message should be kept on the queue. See the documentation of your JMS server on how expired messages are treated.
`ReferenceParameters`	This is essentially a list of key value pairs that will appear as header properties on the JMS message. Common properties for any type of message include: `User` - P360 user name `Password` - password for the P360 user `JMSCorrelationID` for two way communication. P360 will include this as a header property in the response. `SuccessTargetService` - for two way communication this specifies the value of the `P360TargetService` header property in the response. `ErrorTargetService` - for two way communication this can be used optionally to specify a different for `P360TargetService` in error responses. Individual message types may require more properties.

The WSDL includes partner link types. When adding new participants to a BPEL process and selecting a port type for its service interface ActiveVOS automatically creates a separate partner link type in a new WSDL. You can see these new WSDLs pop up under wsdl/bpel in your project structure. While it is not strictly necessary you can change the partner link types of your participants to use the types form the Core WSDL instead. Once you have done this the generated WSDLs should be empty as ActiveVOS Designer realizes you don't need the generated partner link types any more. However they are not removed completely and still appear as imports in your projects. To completely get rid of them, remove the imports first and then the WSDL files.
Always make sure the files just contain an empty root tag before doing this. Also, as the behavior is the same for each new participant you might want to only do this once you have all participants defined.

Workflow interaction examples

Workflow examples are provided in two separate orchestration projects - P360_JMS_Demo and P360_JMS_Demo_DataQuality. The later one contains a DQ execution specific example and the other one has all the other examples. Separation into two projects was arbitrary and just to show that workflow processes can be defined in several projects. Both projects rely on the P360_JMS_Core project for reference to the WSDL and also at run time for the routing functionality.

Workflow instance creation

The NoOpReceiver example workflow contains a minimal workflow. It basically contains a consumer, a variable and a receive activity that assigns the incoming message to the variable. Instances of it will appear in the ActiveVOS monitoring for each message that was successfully received.

Use this workflow for testing your setup for incoming messages:

To test ActiveVOS Message Service setup and P360Router process deployment publish a message to the queue that is monitored by ActiveVOS
- Message Body can be arbitrary XML.
- Message header should include P360TargetService property set to NoOp-Trigger .
- Instances of the workflow should appear in monitoring and the process variable should contain the message body sent.
To test P360 to ActiveVOS communication set up a change trigger in P360 that is sending messages via queue to NoOp-Trigger.
- Instances of the workflow should appear in monitoring and the process variable should contain the message sent from P360.

P360 Service API oneway calls

Note: This example is using the LIST API to issue a write request to P360. The queue based communication support for the write direction of the LIST API is experimental in the current release.

The ServiceApiCallOneway example workflow shows how to invoke P360 from workflows when there is no need to receive a response from P360. Here is a short summary of its content:

It consumes incoming trigger messages at the endpoint ServiceApiCallOneway-Trigger .
- Again, for testing this workflow it should be hooked up with a change trigger definition on P360 side. E.g. whenever the short description of an item changes.
Additionally it contains a Provider and an invoke activity using it for sending a message to the P360 Service API.
- The concrete call is setting the CurrentStatus of the item extracted from the received trigger message to "07 Attributes OK"

Compared to the generic header property description above this call needs additional properties:

Property	Value	Description
`P360Url`	`rest/V2.0/list/Article`	Service API endpoint to invoke on P360 side.
`Method`	`POST`	Does not strictly have to be set as this is the default. Don't be confused if this looks like REST/HTTP. The communication is still JMS based but it is mapped onto the existing REST based API on P360 side.

You can use this workflow to test the full roundtrip P360->ActiveVOS→P360. The trigger message is expected to be an entity change trigger containing the entity type and id. The workflow extracts this information from the incoming message and uses it within the message body of the outgoing request. Set up a change trigger on P360 that reacts on changes to the "short description" on items. Then create some items - they will have their initial "status" set to "01". Changing the short description should lead to the creation of a workflow instance and then to call to P360 that changes the status of the item to "07".

P360 Service API calls with result handling

The ServiceApiCall example workflow shows how to invoke P360 Service API and process the response.

Compared to the one-way example we need two additional Consumer participants, one for the success case and one for the error case. The example uses the "Pick" activity to wait on two endpoints at the same time. Additionally it also has a "timeout" branch defined. There are three possible outcomes:

Response is received on the endpoint waiting for "success" responses → workflow will be shown as completed in monitoring.
Response is received on the endpoint waiting for "error" responses → workflow will be shown as faulted in monitoring.
No response is received within the time set up on the "timeout" branch → workflow will be shown as faulted in monitoring.

This is a simple example. In the real world the workflow might continue in each of these cases but take different decisions based on the outcome of this call.

Note that for the correlating requests a correlation set has been defined using the definition provided in the WSDL. This correlation set is used on the outgoing "invoke" activity and the matching "receive" activities.

The outgoing message has the following header properties set:

Property	Value	Description
`P360Url`	`rest/V2.0/list/Article/byCatalog`	Service API endpoint for listing the items in the master catalog.
`Method`	`GET`	We want to the functionality associated with the GET method in this endpoint.
`ResponseQueueID`	`bpm`	This is the ID of the message queue to which the response should be written as configured in P360 service properties (not the JNDI name used in ActiveVOS!)
`SuccessTargetService`	`ServiceApiCall-Response`	The endpoint to invoke in case of successful execution. The response message will use this as the value for the `P360TargetService` property.
`ErrorTargetService`	`ServiceApiCall-Error`	The endpoint to invoke in case of a failure during execution. The response message will use this as the value for the `P360TargetService` property.
`JMSCorrelationID`	...	Correlation id to match up response with the right workflow instance in ActiveVOS.

Special handling of GET requests

REST/HTTP GET calls do not require/support an input message body. However the request and response are mapped here onto two distinct operations defined in the WSDL and each operation needs an input message:

The request is using the callWithoutParameters and an emptyMessage as input.
The response is using the standard receive operation and the p360RoutedMessage.

So the emptyMessage is essentially a workaround for having to provide a message type for every operation. But there is also a different reason for having it. As described in the section on correlation handling the ActiveVOS engine needs the correlation ID to be part of the outgoing message. So in cases like this we still have to add it to the emptyMessage.

P360 DQ execution with result handling

The CallDataQuality workflow example shows how to execute DQ rule configurations. From a structural perspective in is very similar to the previous example that calls the Service API and waits for the response:

A total of three consumers: initial trigger, success response, error response
A provider for invoking P360 endpoint
A "Pick" activity for reacting on the response from P360
Correlation ID present in both the JMSCorrelationID header property and outgoing message body. Correlation set defined and used on "invoke" and matching "receives".

There are however also some differences:

P360 listens for these requests on a separate queue, so the "address" of the Provider participant needs to be set to the correct JNDI name (JNDI_P360_DATA_QUALITY).
The Service API specific parameters are not needed: P360Url, Method

Note that this workflow assumes that there is a DQ rule configuration present on P360 which is named IsEmpty. It should be defined so that it checks whether the short description of an item is filled or not. For testing add a change trigger on short description changes and invoke CallDataQuality-Trigger endpoint. Add the short description and the DQ status of this rule configuration to the table in the P360 rich client and observe how filling/emptying the short description of an item changes the DQ status.

P360 workflow tasks

The WorkflowTasks workflow example shows how to set up workflow tasks on P360. P360 workflow tasks can be used to include manual tasks by users into the overall workflow.

Workflow task management calls are part of the Service API, so the explanations in the previous examples around Service API calls apply here as well.

The overall structure of the workflow is as follows:

Receive a trigger to start the workflow - expected to be an entity create/change trigger.
Invoke Service API to define the workflow task structure - our case the definition includes two steps/statuses: status01 and status02
1. Note that this is done for each instance of the workflow process. If P360 already knows about the workflow task definition it will ignore this.
  However the workflow could be sending a newer version of the definition which will cause an update on the P360 side.
Tell P360 that the item extracted from the trigger message should "enter" status01.
Wait for message from P360 that states that some user has marked status01 as finished for this item.
Tell P360 that the item extracted from the trigger message should "leave" status01.
Tell P360 that the item extracted from the trigger message should "enter" status02.
Wait for message from P360 that states that some user has marked status01 as finished for this item.
Tell P360 that the item extracted from the trigger message should "leave" status02.

Note that steps 4 and 7 are waiting for messages at certain endpoints: WorkflowTasks-Finish01 and WorflowTasks-Finish02. P360 knows to use these endpoints in the P360TargetService header because they are included in the workflow task definition sent to P360 in step 2.

Correlation is needed between steps 4 and 5 and again between 7 and 8. For this purpose a correlation set is set up similarly to previous examples.