Clone wiki

doc / Guide for BCM v0.5

This is a supplementary summary guide for how to set up the BCM for version 0.15.2

It is highly recommended to review the following slides and the business architect guide.

Please check this step by step tutorial to learn more about EPM and B2B working in practice FIspace B2B Greenhouse sample and the related materials

BCM implements the logic for a business process template (and maintains the runtime state for the individual business process instances).


Note 1: in previous versions, there existed a single combined environment where you both authored and deployed. The authoring stage is now separate from the deployment. After authoring, the configuration can be downloaded, managed (e.g., placed into a Source Control Management system for versioning) and deployed to different environments (e.g., to experimentation).

To get started with authoring, you first need to instantiate a configuration for the appropriate domain. You can do this in the SDK – it generates starting configurations for both ACSI and the Bridge. See the business architect guide for the details of what the starting configuration contains.

After that, zip up the directory and import into ACSI (right click on Your Business Entity Service Centers, select Import Application from Zip, select the file and click Upload. Then refresh the current page – in FIspace Studio you can click the BCM Editor button again). Note for Mac users: using the built-in archive utility to compress will result in the creation of an additional top-level directory inside the zip called __MACOSX and the resulting file won’t be valid. Instead, you can run the zip command from the command line where <ConfName> is the directory to be zipped and is directly under the current directory: zip –r <ConfName>.zip <ConfName>

The common things that need to be configured (based off the starting configuration created by the SDK): refining the business entity, what additional incoming messages will be received, what outgoing messages will be sent to EPM and defining the lifecycle.

A business entity is automatically created by the SDK, using a name provided by the user. Its Information model automatically contains a businessProcessId field. This field is needed so that different business process instances will have separate, and identifiable state.

If your business entity needs to store more state:

  1. Update its Information model by adding more fields to it.

In some case, you may need to differentiate between different business process instances by more than just the business process id. For example, if a farmer is using an advice system for different crops, then there may be a single business process, but the farmer may want to issue several advice requests in parallel, one for each crop. The system must be able to maintain separate and identifiable state for each such process.

If your business entity should be identifiable by more than just its business process id:

  1. Be sure its Information model includes all identifying state.

  2. Later, you will need to update the correlation keys in the siena.xml file to use all identifying state.

  3. Later, you will need to update the bridge configuration XML mapping files.

The starting configuration already includes support for message types which were defined as starting the business process, and for message types which appear in capability type Responses.

If you have additional incoming messages:

  1. You will need to define them under the Event Model. Generally, give them the name matching their type and select the type for both the incoming and outgoing messages.

If you are sending a custom event from EPM to BCM (i.e., an event in EPM that doesn’t have a domain message type) :

  1. It will be received by the Bridge as an EpmBcmGenericMessage.

  2. By default, it will create a new business entity. To customize when it will create a new business entity, or to prevent it from creating a new business entity, refer to the bridge details in the business architect guide.

  3. It will be sent to ACSI. If you want to handle it as an incoming message you will have to:

a. Define a new data-type for it

i. Its name must match the event-name in EPM.

ii. All fields defined for the event in EPM must be defined in ACSI. Define them with a cardinality of n.

b. Define a new event for the message (as explained above).

In some scenarios, BCM may need to send back a message later to close the EPM context. In these cases, it is critical that BCM have all the data necessary to send back to EPM later. Thus, the custom event may need to include this data so that it can be saved in the BCM business entity.

For outgoing messages to EPM (NOTE – this will be done automatically in the starting configuration in the next internal release):

  1. You will define a new External Service for each message – the details of how to do this are given in the business architect guide under the section titled “How to integrate BCM with other components in the platform?”. Basically it should be set up to make a POST to the bridge, specifying the message parameter to be passed (it is important that the message parameter name exactly match that of the message type).

Define a lifecycle:

  1. Create a new root stage for a GSM lifecycle.

  2. You should generally have a milestone defined for the different stages.

  3. To do something with an incoming message you should define a stage with a guard for that event (e.g. self.<Event>.onEvent()). If you don’t see the Event corresponding to that message defined in the Business Entity Information model, you can add it manually.

a. A single step would be to either send a single message or update some state (but not do both of these, or send multiple messages). In these cases, you would mark the stage as atomic, and then indicate whether to Invoke or Assign and then configure the values. To send a message to a capability, Invoke the service matching the appropriate capability type under External Services. To send a message to EPM, Invoke the External Service you defined for sending messages of that type to EPM.

b. If you want to do multiple steps, then define sub-stages and configure them. For example, to send messages to two capability types, we would have two atomic sub-stages each of which Invoke the appropriate External Service.

c. If BCM needs to close an EPM context (This may be necessary when, for example, EPM started the business process, and it shouldn’t start another one until this one completes), then Invoke the close_epm_context External Service. Be sure to set the businessProcessId field. Additionally, you should set the other fields (up to 10 fields) so that EPM can identify the context to close.

  1. It’s a good idea to check that the milestones appear in the Information model. If not, you can add them manually (with a type of boolean and a MaxOccurs of 1).

Finally, download the configuration again as a zip (by right-clicking on it and selecting Download).

Correlation-keys mapping Event incoming messages to Business Entity instances may have to be updated. In particular, if you sent a custom event from EPM to BCM, or if additional fields are necessary to identify the business entity, you will have to do this. The details can be found in the business architect guide and ACSI’s user manual. Generally, beneath each <ca:Event> entry in the XML, there should be a field such as: <ca:CorrelationKey id="<SomeId>" artifactType="<BusinessEntityName>"> <ca:KeyAttribute id="KeyAttribute1" eventXpath="/<EventType>InputMessage/businessProcessId[1]" artifactXpath="/<BusinessEntityName>/businessProcessId" operator="="/> </ca:CorrelationKey> If your business entity should be identifiable by more than just the business process id, add additional KeyAttribute entries for each field, each with its own id, eventXpath and artifactXpath.

Once the correlation keys are defined, re-zip the directory. It is recommended that you replace the instance in the Authoring environment, by removing the old configuration (by right-clicking its name, and selecting Remove) and importing the new zip.

The bridge configuration may also need to be configured:

  1. If your business entities should be identifiable by more than the business process id, you will need to configure marshallers for creating Business Entities to include this information; this is done by using Castor XML Mapping files. If you want to start a business process by using a custom message from EPM, and your business entities are identifiable by more than the business process id, you will need to configure the marshaller for EpmBcmGenericMessage – configuration is done directly inside the application-config.xml file. See the business architect guide for more details.

  2. If you want to customize when business entity creation takes place (i.e., to filter on specific message field values), you will need to update application-config.xml. See the business architect guide for details.

You can deploy to a runtime environment using the SDK.