TIBCO AMX BPM Best Practices versionEMS AMX BPM Guidelines This is a TIBCO ActiveMatrix Guidelines document from TIBCO Professional Services Group. The intended audience for this document is Process Architect & Process Developers. This document provides Business Studio Process Modeling Guidelines. This is not an introduction or overview document. It assumes that readers have advanced knowledge of Business Studio and AMX BPM. This document can be used to establish company specific standards, or simply used as a reference. Document Version: 2.0 Date: 07. July 2016 M BPM Enablement CTS Version (TIBCO) 1
Transcript
TIBCO AMX BPM Best Practices
versionEMS
AMX BPM Guidelines This is a TIBCO ActiveMatrix Guidelines document from TIBCO Professional Services Group. The intended audience for this document is Process Architect & Process Developers. This document provides Business Studio Process Modeling Guidelines. This is not an introduction or overview document. It assumes that readers have advanced knowledge of Business Studio and AMX BPM. This document can be used to establish company specific standards, or simply used as a reference. Document Version: 2.0 Date: 07. July 2016
M
BPM Enablement CTS Version (TIBCO) 1
TIBCO AMX BPM Best Practices
Revision History
Version Date Author Comments
0.1 0.3 2012 Raphael Derbier First Draft 0.3 b 25.2.2013 Jörg Grote first online Version
0.3 c 26.02.2013 Annkathrin Wessel fixed some spelling errors and added some comments
0.4 26.02.2013 Jörg Grote added new Parts for Service Calls in context of Mediations
0.5 22.04.2013 Jeremy Smith Adding AMX infrastructure section
0.6 30.04.2013 Jeremy Smith Added section on AMX queues,TM log files and PER files
0.7 06.08.2013 Jörg Grote added a section for BPM vs. SOA Products
0.7.1 29.08.2013 Raphael Derbier added hints on AMX BPM installation
0.8 05.11.2013 Jörg Grote added RQL, LDAP, Performance Hints
1.0 04.03.2014 Jörg Grote review for a first release
1.1 14.05.2014 Jörg Grote review several Areas and updates
1.3. 07.07.2015 06.10.2015
Jörg Grote added several remarks of Thomas Manson, many thanks! + some minor extensions.
2.0 01.07.2016 Thomas Manson Review for AMX BPM 4.0
GENERAL CONCEPTS used BPM vs. SOA Products BPM vs. SOA Services considerations AMX platform concepts
PAAS Process Pageflow Business Services Deployment
AMX Infrastructure Best Practice AMX Administrator EMS Usage for AMX Transaction Manager Database usage for AMX AMX BPM Product Component Distribution AMX BPM interaction with other implementation types AMX BPM Product Installation
AMX BPM Process Development best practices Business Studio configuration Project organization in Studio Lifecycle, namespace and versioning, Naming convention Process design Form design and development
Applying “Bootstrap” CSS to AMX BPM Forms Step 1 Create a Test AMXBPM Form Step 2 Download Bootstrap Source Code Step 3 Create the “.less” File Step 4 Compile “MyProject_BPM.less” into “MyProject_BPM.css” Step 5 Test the New CSS CSS Reset Data Model design Global Data Model Design
What is it? There are 2 types of global classes: Case class and a Global class. Competitive Advantage Rules to Follow
BPM Enablement CTS Version (TIBCO) 4
TIBCO AMX BPM Best Practices
Global Data vs. MDM Org Model design Page Flows Sub processes Web Service Integration Front End Integration options Exception Handling Testing
AMX BPM Reporting best practices
AMX BPM Operation best practices Obfuscate (crypt) password in configuration files Starting and stop Audit log Archive and purge Project deployment Project upgrade and migration User Management Performance Tuning Best practices Software Management
Content and Warnings This document list some best practices related to the usage of AMX BPM in a project lifecycle. It is not intend to replace any part of the documentation and it is assumed that the reader is familiar with AMX BPM documentation in particular:
TIBCO Business Studio™ Process Modeling User’s Guide (tib_bstudio_modeler_user.pdf)
TIBCO Business Studio™ Forms User’s Guide (tib_bstudio_forms_user.pdf)
TIBCO Business Studio™ BPM Implementation (tib_bstudio_bpm_implementation.pdf)
Best practices should be used as “check list” on your project. For each best practice, evaluate if you should use it in your project or not. You may have good reason not to follow a given best practice as each project has specific context.
CTS document references
The following documents are not part of TIBCO Documentation but provided as project accelerators by TIBCO Customer Technical Services (CTS). They are companions to this BPM best practices document:
TIBCO CTS Guide : BPMN Project Patterns with AMX BPM Business Studio TIBCO CTS Guide : AMX BPM and Service integration Error Catching and Troubleshooting TIBCO CTS Guide : AMX BPM Naming Conventions
BPM Enablement CTS Version (TIBCO) 6
TIBCO AMX BPM Best Practices
GENERAL CONCEPTS used BPM vs. SOA Products The repeat question asked from both sides of the fence is: what is the difference between BPM and SOA? BPM and SOA are two sides of the same coin. Another more concrete response – if 80% of your process is people centric and 20% systems centric, you are looking at BPM vs the other way for SOA. Often mentioned too – it’s all about the user, a more business centric user trying to define a process at the business layer needs BPM vs a technologydeep user defining a process at the system layer, who needs SOA. Last one best: BPM is about extracting high level turnkey business processes and managing them as though they were assets in your organization, while SOA is about rewiring the IT plumbing in your infrastructure for efficiency and reuse; You need those business process assets to leverage your IT plumbing and you want your IT plumbing to always align with business process requirements. While all these responses hold truth in them, the more I’ve worked in both spaces and closely followed them, realize that the lines are blurry which is why people ask this repeat question. And when you think about it, a user wants to talk about finding a solution to the problem he has on hand, rather than be bombarded with three letter acronyms such as BPM and SOA. Vendors such as TIBCO are in a unique position where we have eons of experience in both areas that can leverage across product offerings so we cater to exactly this: provide the solution rather than a piece of technology that should be very carefully mapped to the problem. Another point that is imperative: for the most successful SOA implementations, BPM and awareness of business processes is critical. Only then can you quantify and measure metrics against the business as well as design for the business, rather than just tweak and churn against technology for efficiency. If you read Paul Brown’s book on: “Succeeding with SOA” (highly recommend), he touches on this all through, where he talks about realizing business value through architectural design. Also there is a new Book: "TIBCO Architecture Fundamentals" And the counter, at every point that a business process leverages the underlying infrastructure, a good design will allow it to reach out to an SOA implementation so there is always a loose coupling between BPM and SOA; rather than to hard coded systems interfaces to your business process. This loose coupling between BPM and SOA will allow one layer to change independent of the other. When you reprovision your IT infrastructure, you don't want to bring down your business processes, do you? It’s important for BPM and SOA offerings to work well together – the BPM offering should be able to call out to the SOA services and orchestrations at design time with a few clicks of the mouse and work seamlessly at run time. And an SOA process should be able to call out to BPM centric processes without extensive work or rewiring. The best designs are from experience in both areas. Stick to your expertise be it SOA or BPM but learn extensively on the other area and attend conferences in both areas so you know what's happening on the other side of the fence before you sit down to design your architecture. The takeaway is that BPM and SOA are interdependent and for good reasons, the best implementations leverage the strengths of both while keeping them decoupled.
BPM Enablement CTS Version (TIBCO) 7
TIBCO AMX BPM Best Practices
BPM vs. SOA Services considerations where are a lot more criteria's why should select BPM vs. BW as execution Engine, i.e.
Long running procedures (days, weeks, months) you want to track/audit them may you have SLAs and escalation in you process Human interactions, complex pageflows, or simple approval. even for error handling, you can use BPM
On the other hand you can use BW to build exactly what you need and use JMS Queues & databases to persist necessary milestones and/or areas. In this case you are rebuilding staff that exists already in BPM, like:
AuditTrails, EventCollector Correlation Data Waiting Events Timers BPM Patterns like separation of duties, pilling, distribution strategy, etc. BPM human Inboxes and human tasks, without all this BPMN modeling features
So there is no simple answer about human or completely automated procedures, other areas I would consider are:
Amount of caseinstances per day/hour, i.e. 1000s new caseinstances per minute is not what BPM is built for.
BW is normally not the right choice for long running procedures So as a guidance it is always a mix:
Use BPM for long running business centric procedures; there you need exact business reports & transparency. Make use of BW to create higherlevel composite services, and no detailed audit inside is needed.
Use BW where you have 1000s of caseinstances per minute and use BPM for Exception/Approval/ErrorHandling
BPM Enablement CTS Version (TIBCO) 8
TIBCO AMX BPM Best Practices
AMX platform concepts AMX BPM is an application running on the AMX platform. Take time to understand key AMX concepts by reading : TIBCO ActiveMatrix® Service Grid Administration, chapter ‘runtime environment’ and chapter ‘Application’).
Each BPM project designed in TIBCO Business Studio BPM edition, will create an application also running on AMX Platform and dependant on the amx.bpm application.
PAAS PAAS by definition is exposing your process as a service on the AMX Platform. That basically means, I make the starter event on the process a type "message". I define some parameters. Studio creates a WSDL. I deploy to AMX and I can then call that service over HTTP.
In effect that process becomes a composite application with an exposed service. The composite application has policies attached to the services it exposes (one way transaction). If you want to put something in front of it to do data transformation, expose it over another binding or apply other policies you can use an AMX mediation to expose your BPM service.
Process A BPM Process is always a part fo an AMX BPM Application and uses other Processes out of the same Business Studio Project or reference to other Sub procedures deployed as other Applications, here Data Interfaces are important, to make them reusable.
Pageflow Pageflow is a stateless process. Typically used for user interaction with forms, and service calls to supplement that user interaction. It is stateless so if it stops, you lose stuff. In fact the caller effectively maintains any state anyway so all there is to lose server side is info about your progress through the page flow.
Business Services Business Services are basically a page flow in front of a Process As a Service. They let the user follow a stateless user interaction process (typically from workspace, but could be custom app too) which results in a call to start your "Process as a service". In addition there is an API available that lets you view and start available Business Services from outside workspace.
Deployment An AMX BPM project produces a DAA file deployed on an AMX server.
A project containing at least a process or an organization model and will create on the AMX platform :
A Feature identified by the project id (see properties / lifecycle) and version
An application template identified by the project id (see properties / lifecycle) and version.
A project containing only a Business Object model is not deployed on AMX server.
The deployment of a Project containing a process and referencing the object model will create on the server a copy of 2 jars in [TIBCO Host]/<server name>/host/plugins
Jars are identified by BOM project id and version.
If you undeploy and delete an application containing a BOM and some processes : BOM jar files are removed from the server, application feature and application template remains.
BPM Enablement CTS Version (TIBCO) 9
TIBCO AMX BPM Best Practices
AMX Infrastructure Best Practice This section contains some best practice from the AMX Platform perspective in terms of best practice for a distributed Load Balanced, Highly Available and Fault Tolerant configuration.
AMX Administrator The AMX Administrator component can be deployed stand alone or in Load Balanced mode (activeactive). This is often called “Admin Replication”.
The impact of an admin server outage should be considered when deciding whether Admin Replication is required. The impact is as follows:
Deployed applications will continue to run normally The enterprise cannot be modified (nodes, shared resources etc) Applications cannot be monitored or managed Applications cannot be deployed
Admin Replication requires:
TIBCO_HOME and CONFIG_HOME on same path for both servers Same O/S for both instances Shared File System mounted to same path for both servers External Database used for admin (ie. not HSQL DB)
Admin replication will involve configuring load balancer URL. Internally a load balancer is used to distribute requests. If an external load balancer is used to load balance admin UI requests this should be configured with sticky sessions.
Important: In the event of failure to create Admin replica nodes it is essential that the failed node is removed cleanup by following the steps “Deleting a TIBCO ActiveMatrix Administrator Server Instance” in the AMX installation document.
Further documentation references on admin replication: (look always for newer versions, are versions related to the used Versions)
Installation steps for admin replication also available in BPM documentation library:
AMXBPM 4.1 Admin Replica Guide
Admin replication steps in AMX documentation library:
EMS Usage for AMX The vast majority of implementations have used a single EMS server. This is as per the out of the box default configuration.
As AMX BPM implementations scale to higher volume deployments it is worth considering how AMX is using EMS and how the platform’s use of EMS can be distributed.
AMX in the context of AMX BPM uses EMS in the to facilitate messaging as follows:
1. Notification Server This is to facilitate messaging between hosts, nodes and administrator. It is likely to be low volume messaging and latency is not a major factor.
2. Environment Messaging Bus This is to facilitate messaging between components via virtualisation. Used both at application level BPM process calling services and within AMX BPM itself for example between Work Manager and Process Manager. It has the potential to be high volume messaging and latency could become very relevant
In addition to the above uses of EMS other potential uses are:
1. Logging Service 2. Monitoring Service 3. Internal direct use of of EMS via BW components, Java components or Java POJO
To facilitate load balancing, internal AMX BPM components such as Work Manager and Process Manager use a virtualise policy when calling each others services. This means messages between the internal components will always go over EMS even if both components are on the same node. Hence, EMS performance is important for the Environment Messaging Bus and deterioration in performance (for example high latency or overloaded EMS server from logging messages) will adversely impact BPM performance.
When planning for very high volume BPM implementation it makes sense have a dedicated EMS server for the Environment and one for the Notification Server.
In the future when enterprise may transcend locations for example one environment in London and one in USA it may make sense to have a shared Notification Server EMS, but a local Environment EMS for each environment.
If logging and monitoring services are used it would make sense to deploy those to a dedicated EMS if an existing EMS server is used notification server would be preferred to Environment Messaging Bus EMS.
Hints:
Creating separate JNDI factories even when using same EMS server can help to switch to separate EMS server later
Messaging bus can be changed at a later date but this should be performed under guidance from support team
Use of EMS queues for BPM application deployment
This section provides some details of the EMS queues used by a sample BPM application deployment. It is not complete but aims to give some insight into the EMS queues used for a sample BPM application composite. Example of BPM/EMS Queue Interaction Diagram Once deployed, the initial infeed process (which holds a Start Event of type Message) relies on the Messaging Bus EMS queues depicted in the diagram below. This diagram illustrates the interactions between the BPM app components through EMS queues in this particular case.
BPM Enablement CTS Version (TIBCO) 11
TIBCO AMX BPM Best Practices
When an initial infeed process holds a Start Event of type Message then this Start Event relies on Service Virtualization EMS queues that are created in the Messaging Bus by the custom application the first time it is started in the target runtime environment.
These EMS queues are named as follows:
where:
<environment ID>: Internal ID for the BPMEnvironment <application ID>: Internal ID for this application (com.tibco.cma.pilot.bpm) <component name/path>: CMAPilotPackageProcessFlow derives from the Process Package name (CMAPilotPackage) + suffix ProcessFlow
<service name> XCollFeedComplete derives from the Start Event of type Message in Business Process . OBSFeedComplete with BPM Endpoint Name XCollFeedComplete and is the same as the corresponding Participant Name <service path>: Same as above with this pattern: <promoted service name>...<component service name> <binding name> OBSFeedComplete_EP derives from the Port Type (OBSFeedComplete) used in the same Start Event + suffix _EP (End Point)
BPM Enablement CTS Version (TIBCO) 12
TIBCO AMX BPM Best Practices
Transaction Manager An XA Transaction Manager is embedded in each AMX Node. The data it handles is persisted in two directories: .../tibcohost/<Host Name>/nodes/<Node Name>/work/GeronimoTMID (Transaction IDs & count) .../tibcohost/<Host Name>/nodes/<Node Name>/work/HowlLogs (HOWL Logger files) The Howllogs is one of the rare point where I/O can be limiting the performances on the linux machine that run the BPM Nodes. The HOWL logs is by default 5 files of 10MB max (which is sufficient for most system). Those files contains the ongoing XA transaction. AMXBPM will fill up the first file, then move to the second… and so on until the 10th file, and then go back to the first file. On Startup the files are empty. It’s vital that theses files can grow up to the max file size. Also you may need to move theses files to faster disks. That’s why it’s a good practice to move these file to a dedicated partition (about 200MB would ensure potential future growth), to ensure enough free space available (not taken by logs for example), and may be moved to dedicated disk if needed. This change is done the following way :
Add the following property and value amf.node.txlogdir "/tibco/amxbpm/howllogs" Click Save, then Install with Resolve
Then perform a restart of the node. Check that files are created in /tibco/amxbpm/howllogs
BPM Enablement CTS Version (TIBCO) 13
TIBCO AMX BPM Best Practices
Policy Enforcement Runtime The Policy Enforcement Runtime (PER) is the piece of software that enforces within each node all of the policy sets defined at designtime and deployed through a .daa file. The PER stores its configuration data in an embedded instance of HSQLDB located under directory:
There it updates file PRS_DB.log for every policy set change (e.g. new application deployment, undeployment), with a delay of up to 10 seconds after the change, those changes in file PRS_DB.log being consolidated into file PRS_DB.script whenever the node is shut down. In case of a crash, PRS_DB.log is also consolidated into PRS_DB.script at startup. Files PRS_DB.lck and PRS_DB.properties are also present but not impacted.
Database usage for AMX The main database use for AMX in the AMX:BPM environment other than the BPM operational database is for AMX Administrator data. The AMX Administrator database contains environment configuration.
Logging & Monitoring : those two feature that you choose to install or not in the very last screen of the TCT wizard were known to have serious impact on AMXBPM Performances.
It might not be the case any longer, but so far, I’ve no report on this.
So unless you plan to do some performance testing on the impact of these two services, you should avoid installing them.
Logging & Monitoring :
If logging and monitoring servers are deployed it would be wise to have these on a separate database instance from BPM operational database and Administrator database. Potentially you could separate or share instances for logging, payload (payload for large log events) and monitoring databases.
Do not confuse logging DB with BPM event collector database. For now event collector database must be part of AMX BPM operational database.
Performance is very important for BPM database so in a distributed environment make sure BPM database is fast, and local (low latency) to the BPM nodes.
Databases can be changed at a later date if required.
Don’t share schema names between the different database types. Ideally have them on different database instances.
BPM Enablement CTS Version (TIBCO) 14
TIBCO AMX BPM Best Practices
AMX BPM Product Component Distribution Since AMXBPM 4.0, it’s no longer possible to have “Work Manager” Node & “Process Manager Node”. Those functionality has been grouped together to reduce the number of XA Transaction and increase the performances. Now you only have 3 options : BPMNode, Client Node Type, Server Node Type. TIBCO ActiveMatrix BPM is implemented as a number of independent components that expose
services, exploiting the benefits of the Service Component Architecture (SCA) provided by the TIBCO
ActiveMatrix runtime.
These components are grouped into a set of TIBCO ActiveMatrix logical nodes (of type Client, Server
or BPM), each of which provides a set of services. (An ActiveMatrix logical node is a heterogeneous
group of application fragments that must be deployed to the same physical node.)
The BPM logical node type provides a complete TIBCO ActiveMatrix BPM system, combining the full
capabilities of the Server and Client logical node types.
The sections High Availability and Fault Tolerance Clustered Operation and Specialization and
In this example, TIBCO ActiveMatrix BPM is distributed between three sets of clustered machines,
Clusters 1, 2 and 3.
Cluster 1 runs two logical nodes of type Server.
Cluster 2 runs three logical nodes of type Server.
Cluster 3 runs two logical nodes of type Client.
Note: the Client Node Type do need an access to the Database
Note that in the current implementation (AMX:BPM 2.x) Event Collector is present on all nodes and cannot be distributed in isolation.
From a developer and deployment perspective the above distribution choice is irrelevant. The user application (process application) will be deployed based on the distribution strategy of the amx.bpm.app application. It follows the product distribution automatically. Also notice that BPM development are very loosely tied to technical implementation. Developing on a Single Node developer server and deploying on a multi node server should run exactly the same. (Unlike a BW implementation where running in HA can have side effects (handling files, or
BPM Enablement CTS Version (TIBCO) 17
TIBCO AMX BPM Best Practices
reading topics))
It is NOT possible (or supported) to change the distribution of a BPM user application onto specific nodes via administrator.
It should be noted that instances of each component can be deployed on the same hardware. For example, when a lot of CPU and memory is available, it can be advantageous in terms of performance to have several nodes containing Server Node Type or Client Node Type on the same machine rather than a single node. For more data on this area refer to the AMX:BPM Performance Test documentation published by engineering:
Using the component distribution model above allows a more optimal configuration based on requirements of the system. Many different configurations are possible some examples provided below:
Sample distribution A High user population, mostly user tasks, little STP or service orchestration It would make sense in this scenario to have a large number of Work Manager nodes since it is expected that Work Manager will be highly loaded.
In contrast less Process Manager nodes will probably be required. Sample distribution B Low user population, mostly system tasks Straight Through Processing service orchestration It would make sense in this scenario to have a small number of Work Manager nodes just enough to provide Fault Tolerance.
In contrast, a large number of Process Manager nodes may be required to cope with the large volume of transactions at the process level.
Sample distribution C Remote Users Common best practice is to have all nodes within a BPM environment on the same network. In particular a fast, low latency connection to the database is required to ensure good performance. This is because of the high dependency on the BPM operational database by both Process Manager and Work Manager Components. However, when remote users are required across a remote link it can be advantageous to have a remote node hosting only Web Components. This is to avoid the latency and bandwidth issues that could occur using the web applications such as Workspace, Openspace and Form Client across the slow link. Some DB activity is still performed with Openspace/Workspace, but this is relatively light and typically restricted to configuration data. In particular if a custom User Interface is used this configuration can be particularly advantageous since the form client data (javascript) no longer has to be transferred across a slow link.
AMX BPM interaction with other implementation types
AMX BPM offers the following implementation types:
use of mediation to provide service routing or data transformation, which may be inefficient or less flexible in AMX BPM
use of custom Java components (lift and shift existing code) AMX Decisions
However, it is recommended to use Web Service and connect to Business Works to implement any technical implementation.
AMX BPM must never call a business web service directly, it must always go through a Business Works Layer owned by the AMX BPM project owner.
The reason is that the web services of the customer are likely to evolve, and you shouldn’t have to update AMX BPM implementation for technical reasons. Integration is a job for BW. It’s far easier to redeploy BW project, adapt to technical challenge with BW.
Next, this allows to keep the BPM Data Model clean und Business Friendly and it avoids the Backend changed always need to be adapted by the BPM implementation.
The BW project must be owned by the AMX BPM project to avoid resource issue.
If you need to retrieve some parameters for your process, like deadline duration, consider using the global data for this.
BPM Enablement CTS Version (TIBCO) 19
TIBCO AMX BPM Best Practices
AMX BPM Product Installation
Follow existing documentation for plain AMX BPM install.
Installaon path No Spaces Consider the following Path : /tibco/amxbpm/conf/ tibcohost / AdminAMXBPMAMXBPMServer /data_3.2.x/ The path before tibcohost shouldn’t have any space. The path after tibcohost shouldn’t have any space, it’s done by removing the space in the following screen:
Spaces has caused some issues for upgrading AMXBPM in the past. Space do not get along very well with Java product in general It’s annoying while typing shell commands, scripts. Use camel case or _ to replace spaces. Consistent across environment It should be the same across all environment: this will allow you to duplicate the production environment on non production environment for regression testing (process migration, Hotfix & upgrade) Installation path of AMX BPM can’t be changed after installation. (you may use symbolic link)
BPM Enablement CTS Version (TIBCO) 20
TIBCO AMX BPM Best Practices
Hoix for AMX, AMX BPM & Business Studio and EMS https://edelivery.tibco.com never offer products binaries with hotfixes included.
You must always check https://mft.tibco.com for hotfixes for AMX, AMXBPM & Business Studio & EMS.
AMX BPM have two set of hotfix: AMX HF and AMX BPM HF
Business Studio have two set of hotfix: AMX HF and Business Studio HF
AMX HF level on Business Studio & AMX BPM must be at the same level.
AMX BPM may requires a minimum level of AMX HF. For example, AMX BPM 4.x requires AMX HF12 or later to work.
When installing/upgrading AMX BPM you must go through all of the following document to find install/upgrade instructions:
Follow TIBCO Acve Matrix®Products Co‐Existence Guide for specific configuraons.
Non AMX products:
You should install AMX BPM in its own TIBCO_HOME. Use a separate TIBCO_HOME for BW, EMS, BW Adapters, BW, AS etc…
In production, it’s acceptable to remove/reinstall BW, and redeploy instead of upgrading.
For AMX BPM it’s not an option.
If BW & AMX BPM are in the same TIBCO_HOME, it’s quite difficult to remove BW.
The uninstall my leave some configurations Files or additional Hotfix files, and your Home will be not fully cleared for the new install. AMX BPM & other products do not come from the same Engineering line, do not have the same history.
It has little advantage to use the same TIBCO_HOME.
AMX Products: When installing AMX BPM with other AMX products like AMX ServiceGrid, refer to latest LBN (Late Break News) “ TIBCO Active Matrix®Products CoExistence Guide “
Why
many times customers and partners not aware of this guide, and they are complaining or try to figure out the coexistence install on their own with a lot of effort.
Disaster Recovery If you follow the Disaster Recovery LBN (integrated in the documentation in 2.1 and maybe before) you should not have any problem. Follow install manual + any LBN Article from TIBCO Support.
Important Extracts for the LBN:
use a /etc/hosts aliases for any machine name you reference in AMX BPM (also one for the DB)
use a DB service name alias instead of SID in Oracle . Note that The Oracle JDBC URL is something like this : jdbc:oracle:thin:@amxbpmadmindbhost:1521/amxbpmdb with “/” instead of “:”
Use the same port between TEST, UAT, INT & Production, it makes it easier to duplicate the production.
Why
This simplifies later to add new Servers and/or reinstall new Servers with the same configuration
You can duplicate your production data to a nonproduction environment to test process upgrade, product upgrade. (you should also use the same file system path to be able to duplicate)
Mul nodes / mul servers installaon You need your servers to be connected to a NTP server: The Network Time Protocol (NTP) is used to synchronize the time of a computer client or server to another server. Why Note that in case on time synchro problem you should see warning in the log about PVM:Quartz Scheduler. Same user ID on each linux machine: On linux, be sure to use the same user ID (/etc/passwd id), otherwise you’ll have trouble on the shared folder. In /etc/password, the “tibco” user has a numeric identifier that is used to identify the owner of a file. This number should be the same on each linux machine that host a BPMNode/SystemNode.
Use scripted installaon instead of GUI/Console mode
You need to run the GUI mode once for your setup, and then retrieve the ANT scripts folder: build.xml, build.properties It’s located in the ‘tct’ sub folder of the configuration folder (where the tibcohost folder is). Along with the Disaster Recovery recommendation, you’ll have very few parameter to change from on env to another, and the modification is easier since all setting are gathered in one property file (build.properties). Installation will be quicker since you don’t have to walk through all screen of the TCT Wizard You can run the configuration (build.properties/xml) with TCT For example for configuring JDBC drivers:
BPM Enablement CTS Version (TIBCO) 23
TIBCO AMX BPM Best Practices
#!/bin/bash cd /var/tibco/amxbpm/bin/bpm/4.1/bin/ ./tct tpcl /var/tibco/data/scripted_install/tctjdbcdrivers/scripts/build.properties
To configure a standard BPM development server: (not the one with PostgreSQL DB) #!/bin/bash cd /var/tibco/amxbpm/bin/bpm/4.1/bin/ ./tct bpm /var/tibco/data/scripted_install/tctamxbpmsinglenodeconfiguration/scripts/build.properties
The highlighted keywords vary depending on the operation you want to perform, you can find them here : “Running TIBCO Configuration Tool in Silent Mode” in the installation documentation. https://docs.tibco.com/pub/amxbpm/4.1.0/doc/html/bpmhelp/GUIDA6F4A4FBE6664785A9FB79C2EBA0B027.html
Check the available port (here are the defaults one)
netstat a | grep 6051 netstat a | grep 6001 netstat a | grep 6021 netstat a | grep 6031 netstat a | grep 6081 netstat a | grep 8120 netstat a | grep 10801 netstat a | grep 19767 netstat a | grep 6041 netstat a | grep 8080 netstat a | grep 9091 netstat a | grep 5222 (this one is for the purge SSH console and can’t be changed as of 4.1)
Isolate each environment from each other with VLAN or other technique
It’s mandatory that production can’t be reached by any other environment.
It’s not an AMXBPM specific best practice, just a production best practice.
On HA System, allow connecon between hosts by ssh key
For each ‘tibco’ account of an Highly Available system, generate a private/public key with the following command:
sshkeygen trsa –b2048
For each ‘tibco’ account, edit the ~/.ssh/authorized_keys and add other machine ~/.ssh/id_rsa.pub content in it. chmod 644 ~/.ssh/authorized_keys chmod 755 ~/.ssh/ For each tibco account, ssh to all other machine at least once to test the connection and add the host to the list of know_hosts.
The last one, is just to have xclock on the machine to test the X11 tunnel. To have X11 tunneling working, it must be authorized in SSHD config, you must have XMing installed on a windows PC. You don’t need to modify the DISPLAY variable (either in Putty or on the shell).
Install minimum RPM for linux distribuon with almost nothing on it
sudo yum install compatlibstdc++33.x86_64 bc libXtst.x86_64 Without it the install will fail.
Use a slightly higher value for max open file limit
The install documentation requires only 10’000 max open file limit for installation. But for high loaded system, you’ll need a higher value. So far, 65535 has been enough for most system. (For comparison, Oracle DB install requires more than 131’000 max open file)
Edit /etc/security/limits.conf
And add the following lines :
#TIBCO max open files requirements
tibco soft nofile 65536
tibco hard nofile 65536
#TIBCO max open files requirements
Logout and login again so that the modification is taken into account (no need to reboot). Note : limits.conf can be overriden by files in /etc/security/limits.d/*.conf
Edit the limit configuraon files to tune the max number of process
[root@SIY03P25 limits.d]# vi /etc/security/limits.d / 90nproc.conf
Add the following and remove other duplicates lines : # for tibco, run this 'sysctl a | grep threadsmax' and divide by two the result and set it as soft/hard nproc limit. tibco soft nproc 62847 tibco hard nproc 62847
BPM Enablement CTS Version (TIBCO) 25
TIBCO AMX BPM Best Practices
Apply Disaster Recovery recommendaon from install documentaon
Oracle Service name alias
Get the current service name aliases for the target Oracle instance: SQL> show parameter service_names;
NAME TYPE VALUE service_names string D_WM8CS_OLTP, D_WM8CS_BTCH Add one service name alias for amxbpm : SQL> alter system set service_names=' D_WM8CS_OLTP, D_WM8CS_BTCH , amxbpmdb' scope=spfile; System altered. The JDBC URL is written as follow jdbc:oracle:thin:@*dbhostname*:*dbportnum* / *aliasservicename*
Instead of : jdbc:oracle:thin:@*dbhostname*:*dbportnum**:**servicename**
Use /etc/hosts aliases instead of DNS hostname for each machine involved in the setup
Each machine involved in AMXBPM Setup (EMS, DB, LDAP, WebService Server, SMTP, Load Balancer, servers that hosts amxbpm nodes (System or BPM)) must be designated by an /etc/hosts aliases in /etc/hosts. This make the duplication of production data to nonproduction servers very easy (vs quite difficult), standardize installation process whatever the environment, avoid to have to change hostname on resource template (which can be very long). For web service, use on alias host per logical unit of webservice. Initially they may be pointing to the same IP, but later on, you will probably want to move some to other machine. With an /etc/hosts alias, you just have to edit /etc/hosts IP fo the alias and restart the plateform. 10.100.2.44 virbpm08dev # List of servers used by AMXBPM setup # EMS 10.100.1.1 amxbpmems1 10.100.1.2 amxbpmems2 # AMX Administrator = VIRPMO01 10.100.1.3 amxbpmadminhost # BPM Nodes 10.100.1.4 amxbpmserver01host 10.100.1.5 amxbpmserver01host 10.100.1.6 amxbpmserver01host 10.100.1.7 amxbpmserver01host
BPM Enablement CTS Version (TIBCO) 26
TIBCO AMX BPM Best Practices
10.100.1.8 amxbpmlb # LDAP 10.100.1.9 amxbpmldap #SMTP 10.100.1.10 amxbpmsmtp #webservices (here alias name can have a meaning instead of generic wsX) #virwse03dev.customer.local 10.60.2.25 amxbpmws1 #JmsClient 10.60.2.10 amxbpmws2 #virwso05dev.customer.local 10.60.2.20 amxbpmws3 #virbam03dev.customer.local 10.60.2.4 amxbpmws4 #virbpm03dev.customer.local 10.60.2.3 amxbpmws5 # Databases 10.100.3.10 amxbpmdbhost 10.100.3.10 amxbpmadmindbhost 10.100.3.10 amxbpmbdsdbhost 10.100.3.10 spotfiredbhost
Use a regular EMS user for AMXBPM to connect to EMS
You wouldn’t allow AMXBPM to connect to oracle with the “system” account. The same with EMS ! Here is the script that create an ‘amxbpm’ user on EMS with the minimal set of rights so that AMXBPM operates successfully: create user amxbpm "AMXBPM EMS user" password=amxbpm create queue AMX_SV.> grant queue AMX_SV.> user=amxbpm create, delete, modify, send, receive create topic EMSGMS.> grant topic EMSGMS.> user=amxbpm create, modify, subscribe, publish grant topic $sys.monitor.connection.* user=amxbpm subscribe grant admin user=amxbpm viewconnection create queue com.tibco.amf.admin.deploymentServerQueue.> grant queue com.tibco.amf.admin.deploymentServerQueue.> user=amxbpm create, delete, send, receive
create queue cl_logservice_queue.physical create queue cl_payload_queue.physical create queue amx.governance.stats grant queue cl_logservice_queue.physical user=amxbpm send, receive grant queue cl_payload_queue.physical user=amxbpm send, receive grant queue amx.governance.stats user=amxbpm send, receive
create queue amx.governance.internal.stats grant queue amx.governance.internal.stats user=amxbpm send, receive
commit
Move the EMS configuraon files to a less deep locaon on the filesystem
Because it’s really annoying to navigate in empty directory (cftmgmt folder ..) For example: /tibco/data/ems/7225AMXBPM/*.conf & datastore folder
Rename the bemsd.conf to something more meaningful
For example, rename it to tibemsd7225AMXBPM.conf (other would be tibemsd8225BWDOMAIN.conf, tibemsd8226BWDATA.conf, tibemsd8227BWLOG.conf etc…) This is very useful for scripting (grep the port or the usage) and managing the ems machine.
Change EMS default port
All the TIBCO stack is configured by default to use EMS with port 7222 (client & ems server). Which means that you may get unwanted connection to an env. Change EMS admin default password to something environment specific So that an operation intended on Dev Environment is not executed by mistake on Production.
Edit the factories.conf use the following syntax for all factories URL :
BPM Enablement CTS Version (TIBCO) 28
TIBCO AMX BPM Best Practices
tcp://amxbpmems 1 :8011,tcp://amxbpmems 2 :8011 These hostnames should be in you /etc/hosts of all AMXBPM servers and EMS servers. EMS is acting as a JNDI server with this file, this means that the IP resolution for this host will be done on the AMXBPM machine (not on the EMS servers). For each factory, tune the fault tolerance setting to with FTGenericConnectionFactory] type = generic url = tcp://amxbpmems1:7225,tcp://amxbpmems2:7225 connect_attempt_count = 200 connect_attempt_delay = 1000 reconnect_attempt_count = 200 reconnect_attempt_delay = 2000
Edit the tibemsd7225AMXBPM.conf
Update the path of the files if you moved the configuration folder Change the default port to a non standard(7222) port, ex : 7225 If you want to disable IPV6 support change it to
listen = tcp:// 0.0.0.0 :7225 (0.0.0.0 force ipv4 only) If you don’t have IPv6 properly configured on your system, you’ll get an error on startup. This allow to avoid it.
Enable authorization: authorization = enabled
Rename the log file to .log and with meaningful name : logfile = "/var/tibco/data/ems/7225AMXBPM/datastore/logfileEMS7225AMXBPM.log"
Add the following customization at the end of the file: # Custom properties for AMXBPM # # E.Marchiset / C.Laurent 06/2014 # Client_heartbeat_server = 10 Server_timeout_client_connection = 35 server_heartbeat_client = 10 Client_timeout_server_connection = 35 server_heartbeat_server = 10 Server_timeout_server_connection = 35 reserve_memory = 64MB clock_sync_interval=86400 ####################################
BPM Enablement CTS Version (TIBCO) 29
TIBCO AMX BPM Best Practices
BPM Enablement CTS Version (TIBCO) 30
TIBCO AMX BPM Best Practices
AMX BPM Process Development best practices
Business Studio configuration Configure problem view
From the menu in the upper right of the Problems view, select Configure Contents. This allows you to customize the problems display. Recommended setting is” Error on selected items and children”.
Learn about build opons
Automatic build ensures that generated artifact are updated and checked at any moment, but may be resource consuming, You can disable it, but at this moment you have to build your project when needed.
Also, if a part of your project is quite stable, you can enable the “PreCompile” feature, taht will save you build time :
Right click on the desired project:
If you modify this particular project, you need to disable it, build, and reenable after changes are done.
Add Eclipse plug‐in (SOAP‐UI, bbr gadget)
When testing your bpm application, you may need additional developer tools (SOAPUI for webService tests for example). As TIBCO Business Studio is eclipse based you can add plugins to fit your tests needs.
Adding a Tibbr or Wiki gadget is also a good option to collaborate during the design phase.
Setup Source Control
TIBCO does not provide its own SCM server (Source Control Management), preferring to integrate with the enterprise's choice for SCM.
The Eclipse feature for integrating with such an SCM product is known as the Team Synchronization and has a SVN client installed by default. You may install other eclipse plugin such as CVS or GIT.
Read Business Studio Help, to get instruction on configuring Subversion.
You should contact your SCM vendor for commercial plugins.
BPM Enablement CTS Version (TIBCO) 31
TIBCO AMX BPM Best Practices
Hint:
Processes are stored in an XPDL file.
By default, you have one XPDL file per project that have the process feature enabled.
You should create multiple XPDL files to store set of BPM process that works together.
The idea is to be able to commit/tag/revert easily on these process.
If you put all your process in a single XPDL file, you file lifecycle, from an SCM perspective won’t be fine enough to be useful : Restoring a previous version of the xpdl file to recover the previous implementation of a single process will likely also revert a lot of other process changes.
Also, having large XPDL files in Business Studio is not efficient, as Business Studio has to parse a large XML file, make small updates, revalidate the whole file. Hint
The Business Studio Installer contains “Asset Central Install”, this is basically a TIBCO branded SubVersion Server (SVN). Read Business Studio Help, to get instruction on configuring SubVersion.
Why
Follow soware project best pracces Traceability of Code, DAA, deployments, release
notes, using idenficaon (tags or versions). You must be able to retrieve the complete project on any deployed bpm applicaon;
Collaboraon and reuse
Exclude .daa from svn control :
BPM Enablement CTS Version (TIBCO) 32
TIBCO AMX BPM Best Practices
Configure the presentaon channel you will use in your project
Set the property at project level (Right click on project / Properties / Presentation Channel).
Presentation channel property tab shows the technology used. For example the Openspace Mobile Channel creates new Previews and Project validation.
Or in older Business Studio Versions the Email channel is using GI and forces Business Studio to generate GI views. (not the case starting from AMX BPM 2.x)
Why
avoid generang unnecessary forms, reduce build me
BPM Enablement CTS Version (TIBCO) 33
TIBCO AMX BPM Best Practices
Configure the User profile and domain name
Business Studio: Windows > Preferences > UserProfile
Default domain name is com.example.
Change it to fit your naming convention, so that projects created in this workspace will use the right names
Why
simplifies Naming Convention handling
BPM Enablement CTS Version (TIBCO) 34
TIBCO AMX BPM Best Practices
Project organization in Studio Don’t use spaces in Project Names or Package Names
Newer Business Studio Versions validating this Issue on their own Why Project Names or Package Names are used to auto generate Classes & Paths, some naming conventions not allowing any Spaces, also in WebWorld they get often replaced by some markups automatically.
Close un‐used projects
Rightclick on project in project explorer and select close.
Why
Limit resources loaded in cache. Limit resources on browse panels. When selecting on custom object type for example,
the list will be reduced to classes defined in opened projects. Save build time
Use separate Studio projects for Data, Org, Processes.
A project should be divided in subproject, knowing the possibility below, try choosing the best layout for your use case. There is no unique answer on this topic.
1 Project for Work List Facade
1 Project per Business Object Model (DataModel) for 1 to many processes
1 Project per Case Data Business Object Model (DataModel) for 1 to many processes
n projects with Business Services, Case Actions, Pageflow related to the case Data Model
1 Project with Organizational Model for 1 to many processes
n projects with common subprocesses and process interfaces
n Projects with reusable Sub process Interfaces, and keep them separate from Main & Sub procedures (depended on use case)
n Projects with processes
n Projects with Global Signal Definition
BPM Enablement CTS Version (TIBCO) 35
TIBCO AMX BPM Best Practices
One xpdl per process
Or one main process and a few sub process that are only used by the main process (ex: one sub process reused multiple time within the main process) Why
Beer version control. Xpdl is a single file in the source control. Having mulple xpdl in a single project, helps to fine grained Version control.
Form, Object Model & Org are already stored as separated files.
One main process (xpdl) per project with his subprocesses
The project will lead to one application at deployment time (one DAA), it should contain the smallest meaningful set of processes : one main processes and its subprocesses. The application is a unit of deployment, so if one of the processes needs to be modified, you have to redeploy the application (project) containing that process.
Why
Beer maintenance and lowest non‐regression tesng.
Facade Project
Use Facade as Global List of Work Item List Attributes, use it only for global meaningful Attributes. i.e. Customer Name, Status, Country, current Milestone, etc.
As there can only be one (1) facade project per BPM environment, ensure that all teams have the facade project and don't overwrite other team’s usage of the attributes.
The facade project should limit the definition of a very few common attribute to all BPM process deployed on the system like : Client ID, Contract ID, mobile phone for a phone company etc..
Work Item List Attributes are limited to 40 Attributes. Attributes are typed, use the correct type for better performances. You should not use them all within the same process, or it will have performance impact
on the worklist. Have the minimum required for better performances. There are two (2) attributes that could contain free text Information (255 chars) about a
Workitem (i.e. “Order with Amount of 2395, € ready for high Priority approval from Customer XYZ”)
Define Global Attributes carefully and make use of Attributes delivered by System by default, i.e. Priority, Deadline, Process Name, Task Name, etc.
Bear in mind that not all attributes have DB indexes created (only attributes 1 to 4 have an index). If these attributes are used often, please consider creating DB indexes: store in SVN, the create and drop scripts of these indexes. You’ll need to remove these custom index before upgrading the product, and consider if it’s still necessary after the upgrade.
BPM Enablement CTS Version (TIBCO) 36
TIBCO AMX BPM Best Practices
Lifecycle, namespace and versioning, Naming convention Do not remove the qualifier in Business Studio project
Reminder on the OSGi versioning system : The version is composed of X.Y.Z.Q
X: Major version: incompatible interface change Y:Minor version: compatible interface change Z:Micro version: no interface change, internal Q: Qualifier : the date, ex: 20160721143423 : uniquely identify the version of the DAA
If you don’t put the qualifier, you won’t be able to upgrade the project, unless you change the micro version. The best practice is to leave the qualifier as timestamp by setting the version like “1.6.3.QUALIFIER”. QUALIFIER will be replaced at build time by the current date. The qualifier is helpful to know when things happens. If you want to remove the qualifier for scripted deployment issues, know that you can remove the qualifier in the Ant Script so that your ant script is valid for any version.
Set and apply a naming convenon for AMX BPM project artefact.
Process design Name all artefacts in your process including gateways
Why :
messages in the audit log refer to the acvity name. Process migraon requires named acvies
(and gateway may be good migraon point !).
Specify the interface for each acvity
By default, activities have [All process data] as input. Change it to specify in/out/inout data.
Why :
Mandatory to generate forms. Speed up auto compleon in scripts (ctrl‐space will list only defined parameters) Improve script quality by forcing a usage of specified data. Avoid side effects on Parameters (if you add a parameter for a Receive Tasks, and your startTask has all parameters, then your startTask has an unwanted addional parameter) Less data passed from one part to another of the AMX BPM Engine
BPM Enablement CTS Version (TIBCO) 38
TIBCO AMX BPM Best Practices
Use colours and shape size to idenfy happy path and type of tasks
Following diagram using green for the happy path, red for rejection/escalation tasks, yellow for communication/information tasks and blue for technical/service task.
Happy Path is not necessarily the only thing you want to highlight in the process.
Colors can be used to identify categories of user per tasks (local manager, regional manager, national manager), as there are a lot of interaction at different level + use of Swimlanes.
So use colors to highlight what is important for the BPM process. Task Icon’s can be changed to help with this.
Why :
Readability/Maintainability Help test scenario
Use swimlanes to organize your process
Each lane would be one major phase of your process. Swim Lane are here for process readability, so use it as long as it make your process easier to read & understand.
BPM Enablement CTS Version (TIBCO) 39
TIBCO AMX BPM Best Practices
Document User Tasks and Service Tasks
Use the description tab, on the property view to document (at least) user tasks and service tasks. It should be short text.
Add at least the following information for User Tasks: Business Purpose of the user tasks.
Ex: check the client insurance is covering the declared accident Add details about how the user will do that:
check the date of the accident is within the contact range check the accident has been reported in time …
What data must the activity produce, example: accident coverage accepted (yes,no, pending) ask for legal department adivsories (yes/no) corrected estimated accident cost.
What data is required to achieve this activity, especially for BPM related data. Ex: if you need a group name to build an RQL expression
Who is doing the task : Agent of the Service X, with abilities Y, and can handle accident with estimated cost of the workitem
Is there any deadline and how it’s calculated. (ex: a deadline is set at workitem arrival date + 7 working days to raise a warning to supervisor, as we must answer before day 10)
Why :
When collecng the business needs of your clients, it’s a guidance to get a complete business descripon of the process. As asking these quesons will make the client think of other aspect of the process. (to get this info, you must add a user task to this department etc…)
Documenting helps new BPM developer to understand the project the documentation can be exported and put on a web site it’s the closest place to execution (what the company is really doing) to put your
documentation It Helps test scenario
Learn to use BPMN correctly especially for signal, complex gateways, terminate event.
Signal may simplify your design for example to cancel an escalation process when the work is done. End event does not imply the end of the process as you may have other branches running (escalation subprocess for example), use terminate if you want to end your process. Gateway have some powerful patterns (event gateway, vote, ...), learn and build your own sample process solving recurrent business scenarios.
There are several areas to get an overview:
TIBCO DeliverIt , PSG Wiki and older EVF (handled by TIBCO PSG) TIBCO TEN (handled by TIBCO Education) e.g. http://www.workflowpatterns.com/
Patterns are a good way of describing recurrent problems and their solution. Patterns usage speeds up people learning curve and also improves quality by consistent design (same problem solved the same way each time).
It’s a good software project practice to have a design documentation including used patterns and newly discovered patterns. Pattern may be :
Part of process (it may be stored as Fragment ) Subprocess Use of AMXBPM features with other technologies to provide some feature
Worklist + Custom UI prefiltering to address distribution issues AMXBPM + Event Collector publishing on EC_TOPIC + BW to handle a feature
that would require a service task before each user task (like : status update in custom DB, compute of an RQL for the next task)
Refer to “TIBCO CTS Guide : BPMN Patterns with Business Studio” and enrich it with your own solution patterns .
Eventing
Use the intermediate event when appropriate rather than a split. This ensures that the process remains migrateable for future changes.
When using receive task / catch message events use the correlation timeout (resource tab) make sure you understand how this works (see docs) as expired messages are only cleared on a poll period (30 mins).
For catch message event ALWAYS select serialize concurrent flows until further notice. DON’T use allow concurrent flows.
When using intermediate events try to avoid including execution logic within the event handler flow. Instead try to signal the main flow for example to update a work item or cancel a task. Intermediate event flows should be short lived.
Work Item updates
Don't cancel work‐item and re‐create. This makes reporting tricky and masks task timings. Instead use intermediate event to send signal and update workitem data etc. Update of offerset is now automatically done by AMXBPM since 3.1.
Sub Processes
Where appropriate make use of dynamic sub‐processes rather than normal sub‐processes Why
To break the dependency between main process and subprocess DAA, which allow you to update the sub processes without having the main project being in waiting for dependencies.
Dynamic sub processes also allow the subprocess to be determined at runtime for example using substitution variable , decision table or DB table lookup. This may make future process upgrades easier.
You can also combine this with a loop, to run an arbitrary number of any subprocess that implements an interface
If you need request/reply ‐ try to use the "return process ID" feature This is more efficient, rather than sending a reply message. Most performant option is “inonly” message there are ways to make this reasonably reliable via logging and sending in appropriate correlation data.
Do not have implementation like : Start>script or service task>Reply.
You should instead execute the script/service task in BW and then start the BPM Process with the wanted data. If you need to notify an external system that a BPM process has started, use the Event Collector EC_TOPIC publishing on EMS feature, have a BW engine subscribe to the Topic and forward the information.
With a one way message you have side effect that you have no clue if the process start is successful or not from a client point of view. (errors are still visible in the Event Collector)
Business Service
When starting a BPM process from a business service, if you need a reply switch the send message task to a service task and choose BPM process WSDL. You can then wire to business process using virtualisation.
When starting a BPM process form a business service understand that the BPM process will run with the context of the calling user ID.
Don’t remove a user/resource who has active business processes! Instead have LDAP remove or disable the user, so they can't login anymore, as the authentication against the ldap fails but processes will be still able to execute.
Rules
Make stuff configurable in decision tables, external DB or substuon variables where appropriate
This can enable business to change behaviour without changing the processes.
Externalize relevant parameters for your process using one of:
Forms : You can compute your rule on submit of the form. It’s a solution that works most of the time. Storing forms in pageflow on an external project make them easily upgradable. With Custom UI, you can update your J2EE EAR without touching the BPM Process.
Global Data Lookup Substitution variables
Global Data Lookup samples are stored in EVF Product Area of ActiveMatrix BPM under Delivery 06. Development Samples & Templates.
With Global data and a few Business Service, you’ll be able to have a CRUD interface for administrator.
Other methods below are for preAMXBPM 3.0. Substitution variables can be used by retrieved via a mediation to lookup the value using a property mapped to substitution variable. Make sure you wire from BPM to mediation using virtualisation.
Alternatively a Java Composite can be written to return all relevant values for substitution variables.
Studio/Process Packages
Refer to available Studio structuring recommendations in addition:
Make sure you don't include lots of processes in the same .xpdl file. This can make changes slow. Instead have multiple xpdl in the project and multiple projects where relevant. It’s also better from a source control point of view to have multiple xpdl.
Make sure the BPM objects included/referenced are essential for the project having loads of BDS objects will slow down studio and productivity
Use Working Sets feature of studio to package together relevant projects.
Never open all projects. Start with a workspace of closed projects and just open the one you need (and choose open referenced projects).
BPM Enablement CTS Version (TIBCO) 43
TIBCO AMX BPM Best Practices
Form design and development Separate Pageflows/forms and BPM Process in two different projects
When developing with BS Forms, you must use
One project for BPM Process Another project to store Pageflow and forms
The reason is that
the forms of your BPM process is likely to evolve a lot, while your BPM process will remain stable. Using a pageflow project allow you to update the forms without updating the bpm process.
It encourages your to split your object model in two different BOM, which will make your life easier:
One for the business process (data for : routing, addressing, workitem attributes, deadline)
One for the user interface related data Upgrading a Pageflow project is immediate and easy. Upgrading a BPM Process is more complicated, and migration of process instance to the last version (to benefit of the last update) is more complicate and requires extended testing. When upgrading the User Interface, you’re likely to want that the modification is taken into account immediately by new process instance and old process instance. A visual example :
V1 of the form : the background should be a sliver color V2 of the form : the background should be a light green V3 of the form : the background should be a light blue
If you don’t use separate project to store pageflow/forms, you’ll have process instance with each of the background colors, because you’ll have workitem in the user task at each upgrade, and even if you set migration point, the workitem need to arrive at a migration point to migrate. Also, if you have parallel path, workitem won’t be migrated until they leave the parallel path. Now, background color may seem insignificant (but for quite some business this is already a major issue), but now replace the form update with new business rules :
Bug fix on form validation Rule that set the boolean field use4EyesValidation depending on the amount of the loan
⇒ you can see that it’s really important that the updates can be effective now. You must use a pageflow because :
You can’t reference a form located in another project At the beginning of the pageflow, you need to retrieve your Visual Object Model : the part
of your object model that are not relevant to the BPM Process, but only for the User Interface. (ex: an address is not useful for the BPM (not used in routing, adressing or workitem attributes) but still requires to be displayed or editable in the forms.
BPM Enablement CTS Version (TIBCO) 44
TIBCO AMX BPM Best Practices
The dependency between the main project (the one with the Business Process) and the Pageflow/form project works as follow:
From an AMX point of you, you can change any version part of the pageflow project (Major/Minor/Micro/Qualifier), AMX Administrator won’t put the main project in waiting for dependencies (tested in AMXBPM 4.1, AMX 3.3.0HF13)
But from a BPM Runtime point of view, You can change Minor, Micro & Qualifier version of the pageflow project, and the
project will work as expected : you’ll be able to deploy the pageflow project, and the new version of the pageflow/forms will be running for all existing process instances.
if you increase the Major version, you’ll get an error when opening a form (see below for a sample error).
Sample error if you change the major version of the pageflow project (without updating/redeploying the main project) : 09 Aug 2016 16:32:22,830 [httpConnector_23] [ERROR] com.tibco.n2.wp.extender.rest.WPRESTServlet [ERROR] WPEXT_INTERNAL_SERVICE_FAULT Internal Service Fault nodeName=`BPMNode`, hostName=`centos6.busybox`, componentId=`WPEXT`, creationTime=`20160809T14:32:22.830Z`, extendedMessage=`com.tibco.n2.pfe.services.InternalServiceFault: com.tibco.n2.pfe.internal.exception.PageFlowExecutionException: Error getting bundle information for module [Module Name : [/PageflowTestSub/Process Packages/PageflowTestSub.xpdl] Version [1.0.0]]; has it been undeployed? [com.tibco.n2.pfe.internal.exception.PageFlowExecutionException: Error getting bundle information for module [Module Name : [/PageflowTestSub/Process Packages/PageflowTestSub.xpdl] Version [1.0.0]]; has it been undeployed?]`, componentClassName=`com.tibco.n2.wp.extender.rest.WPRESTServlet`, methodId=`doChaining`, requestReceived=`null`, threadId=`4120`, parentContextId=`null`, environmentName=`BPMEnvironment`, correlationId=``, id=`27139`, stackTrace=`com.tibco.n2.wp.services.InternalServiceFault: com.tibco.n2.pfe.services.InternalServiceFault: com.tibco.n2.pfe.internal.exception.PageFlowExecutionException: Error getting bundle information for module [Module Name : [/PageflowTestSub/Process Packages/PageflowTestSub.xpdl] Version [1.0.0]]; has it been undeployed?[com.tibco.n2.pfe.internal.exception.PageFlowExecutionException: Error getting bundle information for module [Module Name : [/PageflowTestSub/Process Packages/PageflowTestSub.xpdl] Version [1.0.0]]; has it been undeployed?]
BPM Enablement CTS Version (TIBCO) 45
TIBCO AMX BPM Best Practices
Read the AMXBPM Forms Users Guide and in parcular the Tips and Tricks secon.
Form User Guide: https://docs.tibco.com/pub/amxbpm/4.1.0/doc/html/bpmhelp/GUIDFECF6F13A7CE4EB0B3A0241B03E2FC8E.html Tips & Tricks section: https://docs.tibco.com/pub/amxbpm/4.1.0/doc/html/bpmhelp/GUID2A92E7B18BD142BAB3A6785C40B12737.html
Augment data validaon with validaon rules
Example: if a date has to be in the future you should add this rule in the presentation layer using the validation rule. Refer to BS Help: Business Analyst Guides > Forms User’s Guide > Tasks > Valid ating Data in a Form
Use embedded forms
As soon an object appears in several forms, it is a candidate for embedded form.
Create an empty Embedded form and drag & drop the BOM Class from the project explorer on the form. Then manually move the BOM Class Pane up and remove the now empty pane (‘Client Embedded’ below)
⇒
You can put some logic and parameters to the embedded form to reuse it with different behaviors. For example, an embedded form showing customer information may be used as readonly or editable (just create ‘isReadonly’ parameter and bind it with the pane edit property). The same embedded form may also have an extended and limited version (bind visibility of extended field to an ‘extendedView’ parameter.
For dynamic behaviour in embedded forms, add simple parameters and visbility/enablement/etc. rules to the embeddable form and bind them to something in the outer form. Then rules/scripts in the outer form can control the UI state of the inner form simply by setting the “binding” properties.
Store embedded forms at the same level than the forms
Store embedded forms, at the same level than the forms to avoid relative path issue.
From the “Forms” root folder, Embedded forms have the same folder hierarchy level as the forms that will use it. This will make the things easy when it comes to using path to image/javascript etc… from the Embedded forms and regular forms.
If you don’t use the same hierarchy, you’ll have a working Embedded form with image path like “../../images/background.png”.
But when used in a User Task from that will have a different folder hierarchy, the relative path that will work will need to be : “ ../ ../../images/background.png” (ex: one additional level deeper), so your image link won’t work when deployed.
Keep the form complexity low by using pageflow to break it down into simple forms
Avoid trying to cram the entire application into a single form. We've seen some insane examples with hundreds of panes and thousands of controls and bindings such patterns never perform well, use large amounts of memory and are hard to develop and maintain. Instead , use a pageflow to break forms into manageable chunks each with a specific focus and use navigator / toolbar buttons with rules to set INOUT state parameters to certain values then to submit the form. The state parameters, bound to pageflow data fields, can be used to decide which form is presented next.
Debugging forms
In Business Studio Preview, right click, properties and get the URL of the page, past it in Firefox with Firebug or Google Chrome and use the developper tools to debug the behavior of your form (JS debugger, explore the CSS, modify CSS/JS in the developper tools to preview the effect without reloading the form, when you get what you want copy back in Business Studio)
Use logging from the form script. User logger.debug and other appropriate level.
BPM Enablement CTS Version (TIBCO) 47
TIBCO AMX BPM Best Practices
App Dev: Use the RAD/JAD mode to develop within the application context instead of form
Keeping the default buttons leads to a consistent UI for the user (instead of having a named button that change data and submit)
From a developer point of view, it’s also way simpler to handle.
Let say you have the following option for “Accept Request” “Reject Request” “Escalate for Approval”.
The best way to code it, is to have a radio button, which will then display additional field specific to each option (Reject reason, escalate for approval: choose the approver, provide comments)
You can’t achieve the above with buttons “Accept” “Reject” “Escalate”, also you still need the “Save” and “Cancel” button, which makes a lot of buttons. And the UI is not consistent, so it might make the user loose time, make mistakes.
Also, thing may be even more complicated than the above example
Change default buons
Default button are Cancel, Submit, Close. You often need at least to rename the submit button and probably need to add additional submit buttons for different options. For example : ‘Accept Request’, ‘Reject Request’. Use scripts to update data accordingly before submitting.
CSS Contenon ‐ TIBCO Forms vs External CSS Libraries
Forms generated in Studio are using classes like .container that are also used by CSS frameworks like Bootstrap. When the form is displayed in a Custom Application using css. Form developer must take special action to ensure that the forms is displayed correctly in the container application and that css conflicts are resolved. There are 2 types of possible interactions:
1. a css rule defined for the form has an impact on the frontend application. 2. a css rule defined by a css file loaded by the frontend application has an impact on the
form. To solve problem 1: use a parent class name, like 'customForm' or 'mainpane', in Studio form. This will allow custom form css selector to be ".customForm .xxxx". So we are sure that those rules will not interfere with the frontend. To solve problem 2: control the rendering of form elements (radio, container, labels, ...) in the custom css. We may also apply a “CSS Reset” stylesheet containing common HTML classes reset back to browser defaults at the form level.
Avoid using !important in your CSS Class
"!important", this CSS qualifier can be added to any CSS Class definition, it mean this one has always
priority and overwrites other definitions.
Ex: .field backgroundcolor: red !important;
This is true for the whole Browser DOM, and nothing can overwrite it.
It is a general CSS best practice to specify the path to the object you want to customize as detailed as
possible, this allow other definitions and no side effects.
Learn about when to use Stac & Deferred Rendering to improve performances:
The form performance can be improved by activating one of the two options, which will improve the user experience
Deferred Rendering: (for object that are not initially visible) https://docs.tibco.com/pub/amxbpm/4.1.0/doc/html/bpmhelp/GUID94469DBB2E2743CC9C99BEBED25DFD1D.html
Put reusable scripts in a javascript resource file.
You can link a JS file as a form resource to reuse scripts.
Whenever you’re about to write (copy/paste) the same code twice (in the same form or across forms), put this code in an external javascript file.
Some Javascript that may not be validated by BusinessStudio but which are correct (for example you’re using a JQuery function that BS is not aware of), should be encapsulated in a function in an external JS file, and then call the function from the form.
Use target Browser for Form CSS Styling in Preview IE, Chrome, Firefox are working sometimes different in CSS. Also the Browser Tools are often helpful for Style changes.
To preview in your specific browser : open preview in Studio, right click in a blank part of the preview to get ‘Properties’. Copy the entire URL and paste it in your target browser.
Use Firefox Firebug, or Chrome/IE to find CSS Tags & Names (i.e. press F12) All of this WebDeveloper Tools containing Tools to select Objects directly on the Form to see all the applied CSS Styles.
Do not use html ID in you javascript, those are autogenerated and will change over time, which will break your code.
Mobile Forms Note that you can test (runtime) the mobile channel in some browser (safari for instance) on a desktop computer. To do so specify in the URL tibco_channel=mobile :
http://localhost:8080/openspace/mobile/mobile.html?tibco_channel=mobile so as to fool your browser and render the form when your device is not a mobile one…
A CSS Reset file is a stylesheet that resets a specific set of styles back to a consistent baseline (often the web browser default style).
You might wish to only reset just a small subset of HTML elements (to preserve the majority of other custom styles tweaks), or if you prefer you could use a generic "reset" to attempt to get everything back to default/baseline state for a particular form useful when embedding BPM components inside other custom UI.
Best practice is to only reset the HTML elements that are causing trouble, rather than performing a "blanket" reset of everything because:
It's less work for the browser (makes you page load a little faster) It won't overwrite other style tweaks which you may actually want to be included in the BPM Form.
Eric Meyer's CSS Reset Source Code: http://meyerweb.com/eric/tools/css/reset/
Here's another website containing some examples of CSS reset stylesheets: http://cssreset.com/ What is a CSS Reset? Which CSS Reset Should I Use?
Data Model design Read chapter “Business Data Modeling Best Practice “ in TIBCO ActiveMatrix® BPM Business Data Services. (tib_amx_bpm_bds_developer.pdf). https://docs.tibco.com/pub/amxbpm/4.1.0/doc/html/bpmhelp/GUID5C08CB8DFC314E9F9CFC608BC7F4612D.html
Have two BOM : one for the BPM process, one for the forms
In the BPM process, the only data you need are the following : Data for the worklist (process attributes) Data for routing (it should be boolean or integer, do not put logic in your BPM process like
amount >10000 <= this will change over time, put the rules in the forms, put in a separate project so that you can redeploy easily)
Data for addressing: data for RQL essentially Data for deadline Data for Correlation (often it’s in the data for the work list)
Other data are irrelevant for the BPM Process. You should have a Visual Org Model, that contains all other data that are not impacting the business process. Use pageflow stored in another project, like this you’ll be able to change the UI as long as you keep the same major version. UI is likely to change 10 time more than your process. Being able to update the UI without having to upgrade the BPM Process will save you a lot of time (no process migration to implement) Your BPM process will be more simple, quicker to implement, less need to change it : no complex object to manipulate ! Your pageflow first task will be to retrieve the rest of the data (External DB, global data/case data)
In BPM, model for UI effecveness and not for object oriented beauty.
Objects are used as input and output of user tasks and studio generates UI controls from the datamodel. A correct data model with UI in mind , can speed up UI development by minimizing the manual work you have to do on the form when it is generated.
Limit the amount of data passed to a form or pageflow to the data required. Data is loaded as a JSON object in the browser. Don’t pass huge object like a global context, just for few references. Think about a reduced context information set for forms.
Use separate BOM to define services messages (request response) if needed.
When creating services (WSDL) from BOM, you may need to create additional classes to reflect service inputs and outputs (SOAP messages). You may use a separate BOM to create those classes (which will contain attributes referencing your Data Model).
Global Data Model Design Choose CAREFULLY which data should be a “global” data. A global data project should contain data that will be referenced across multiple processes and process instances. Careful thought and design must be put into the structure of global data do not just make all data part of a global data project as these objects are created as tables and stored in the database. Regarding the global data database, it is considered best practice to use a different schema/tablespace for the storage of this data, as opposed to combining it with the AMX BPM schema.
What is it? ModelDriven Storage for BPM Data Life Cycle: It starts with a Process (Pageflow or BPM ProcessInstance)
Data stays in the Store also in case a ProcessInstance ends Data can be accessed by multiple ProcessInstances
Data is store in real Tables, no key/value or XMLBlob, Data can be accessed easily by Reporting i.e. Spotfire Data can be accessed by a generic BPM API
There are 2 types of global classes: Case class and a Global class. Case class are a specialized version of Global Class for case management usage. Case classes must contain a case identifier . The case identifier can be
automatically generated (autoincremented id), Custom : You provide the value (for example, so that it matches the primary key of an
external DB) A composition. If a composition is used, a minimum of 2 case identifiers must be defined.
A Case class must contain a “ case state ” field, the type of this field is an enumeration. Base on the state of the Case class, you’ll be able to call a subset of case action. For example, a Customer case class will have the following states, and case actions
Prospection In Progress Start subscription Set as not interested
Prospect not interested Subscription in Progress
Add Mobile, Add phone device, Add TV Set, Add Land Line Evaluate client solvability Place order and set Active
Active Claim Handling
BPM Enablement CTS Version (TIBCO) 55
TIBCO AMX BPM Best Practices
Order new service Cancel existing service Cancel all and set inactive
Inactive Reactivate
Active With Paiement error Start fund recovery process
Fraud alert Case classes can be referenced on forms and directly updated, based on the data captured on the form. When referencing case class references, be sure to fetch the latest data first, bearing in mind there could be other processes active which may have resulted in a change in data. AMXBPM handle a version for each case instance, to be sure you’re not overwriting someone else data without knowing. Right click on a case, and you’ll be able to generate Business Service to Create, Update, Delete a case. Business Service are accessible outside of a Case context. So you’ll use a “Create” Business Service to create a new customer for example. You can also generate “Case Action” to view or update the case data, which is a special type of pageflow, that can be triggered only when the case have a certain set of state, or only with specific privileges. You must be within a case context to invoke a case action. For example, I open Customer X case, and click the “create Order” to create an order for Customer X. On the case action, general tab, check the states and privileges fieldset below :
BPM Enablement CTS Version (TIBCO) 56
TIBCO AMX BPM Best Practices
Use the “case action” and “Business service” generation to generate template of service.
You can then combine them to achieve functionality very quickly.
For example, I’ve an “Customer” Case object and an “Order” case object.
We want to create an order for the customer, here are the steps :
Create a Case Action named “create Order” to view the case data on the Customer : this way we have the case action, with the customer reference.
Remove the content of the case action Create a Business Service to create an Order, add a CustomerRef as parameter Drag & drop the Create Order Business Service in the “create Order” case action Map the customer ref in the Business Service input Add a service task to link the Customer and Order (Global Data Operation, Change or
Delete, “Add link to other case object” Enhance the Order Form creation
Create Order Case Action for Customer Class:
Create Order Business Service:
BPM Enablement CTS Version (TIBCO) 57
TIBCO AMX BPM Best Practices
Update Order with Customer Ref service task:
Associate Case Reference to process instance and workitem
If you add a case reference on an UserTask interface, or as process field or parameter, you’ll be able to view the linked workitem and process instance from a Case.
This is very handy to have a 360° view of your case.
For example, for a customer case, you’ll be able to see any ongoing claim process, order progress etc…
BPM Enablement CTS Version (TIBCO) 58
TIBCO AMX BPM Best Practices
Case Data update: you can have BPM process subscribe to update event
For example, you have a process that rely on a specific date of a case object, you can subscribe to the case updates, check if the date is changed, and update the date if so in your process:
Competitive Advantage In contrast to other BPM vendors this is a major differentiator. Other vendors stick all their case data in blobs which makes it hard to access.
Rules to Follow Define Global Data to support Model Driven Forms Create Embeddable Form Components for Global Data Classes Define Global Data Searchable Fields as needed
Background: a DBIndex is created for every SearchField. use Pageflows for BPM Tasks, to read Data as Reference
BPM Enablement CTS Version (TIBCO) 59
TIBCO AMX BPM Best Practices
Background: Data gets automatically written back to the Store, short time between read&write.
don’t store a Global Data Reference for a long period of Time in a BPM processinstance. Background: In case data is updated, only readers afterwards can update Data.
Try to avoid Global Data usage if it duplicates Backend Enterprise Data. Better use in this cases directly a Service to the Backend Data.
Use Global Data only for BPM relevant Data, or Search Data. The following tasks are the ‘don’t’ you should care about as well:
Destructive changes should not be made, post deployment: Do not change field names Do not change field types
Don’t store a Global Data Reference for a long period of Time in a BPM processinstance. Background: In case data is updated, only readers afterwards can update Data. Avoid Global Data usage if it duplicates Backend Enterprise Data, rather use service to invoke the Backend and retrieve the data, or have a case data object that is a
light proxy of your data: only ID and searchable field in Case Data.
Global Data vs. MDM Before we can really compare this we need to clarify the below questions
1. Will spotfire be able to easily pull that data from MDM for reporting? 2. How does MDM store data is it just XML blobs again if so we just went back to what we
had before! 3. How does MDM scale will it be able to perform with BPM loads constantly querying it
example our 25,000 user test querying customer data every time a work item is processed 4. Is MDM fault tolerant to match BPMs fault tolerance (you're only as fault tolerant as your
least fault tolerant component!) 5. Perhaps a better approach is for MDM to send notifications when data changes and we
update our global data objects I believe this is a well established MDM pattern. Use case references in process data and work item interface for case to process traceability. Cases are associated with work items that are outstanding with that caseRef Cases are associated with process instances that contain a field containing that caseRef
BPM Enablement CTS Version (TIBCO) 60
TIBCO AMX BPM Best Practices
Org Model design
Use the Organization Model to govern access to work, not to model the full company structure.
Capabilities (with qualifiers) associated with organization units/positions or groups can be very useful to assign work to a user.
In some case, you may want to use a prefilter on the work list instead of using a position/capability, to increase your flexibility/match your requirements.
Use Org Model groups to simplify ‘management or configuraon’ privileges sengs.
Some privileges are used for ‘management and configuration’ for example system action or workspace customization (in opposition to privileges used for business reasons like privilege to validate a contract …). A user will inherit the privileges due to his mapping in the org model. Using groups for each privilege is an easy and flexible way to assign privileges at runtime : you simply have to map a user to the correct groups to set the needed privileges.
As those privileges are not “business oriented”, having them separated from the business org model (org unit / positions) is more flexible.
Use naming convenon to handle System acons and privileges configuraon.
Using groups for privileges can be enhanced by naming conventions to relate group names to privilege names.
BPM Enablement CTS Version (TIBCO) 61
TIBCO AMX BPM Best Practices
RQL Prefer “dynamic parcipant” to RQL when possible. > Refer to dynamic participant best practice > TO REFERENCE. Maintain all deployed org models on a server at the same major version.
AMX BPM <= v.2.1 only You can deploy several org models on a server (let say orgA and orgB). Allocation of tasks using RQL statements will use the highest major version deployed. If you deployed orgB version 2 and orgA version 1, RQL using orgA elements will not be found: RQL is searching for version 2.
Since V2.2 , a V2 and V3 can run altogether. See https://docs.tibco.com/pub/amxbpm/3.1.0/doc/html/bpmhelp/GUID5A3F0B2FED1B4FE38BF4B259CD40B895.html
Use BU’s, Posions & Groups for fast RQL execuon, at least in Chaining Groups Because of RQL execution Performance follow the following rules, to execute the Queries as fast as possible:
small Results < 200 800 ms usage of Groups < 200 800 ms usage of Positions < 200 800 ms usage of Business Units < 200 800 ms usage of UNION < 200 800 ms usage of INTERSECT < 200 800 ms big Query Strings with lot of restrictions < 200 800 ms usage of .all (with small results) < 200 800 ms
Work Allocation
Try to allocate work to org unit or position using a participant rather than RQL wherever possible. This allows use of supervisor views and it perform better.
If you use RQL be aware of limitations in AMX BPM v.2.x (no supervisor views and no dynamic offer set calculation) work around that with:
Have a dummy user, in a dummy position that sees ALL work offered (union on RQL statement)
Allocate supervisors system action to view the dummy users worklist Use attributes to provide appropriate filters on that dummy worklist to provide "supervisor
views" of offered work To update offer set select all items in dummy worklist,
allocate to dummy user then reoffer No longer needed in 3.1
Page Flows Opmise your page flow for performance as user experience is everything ‐ page flows must run fast.
If you read data from a DB do it within the page flow with a DB task instead of reading it from the main process
prefer a single call to get all data required for the forms instead of many service calls.
consider caching static data in a java composite using hibernate for persistent storage of static data or easier : use BW + Active Spaces (or equivalent) to cache DB/Service query
Excepon handling in page flows (with sub‐procs) should be done at top level
aim to return a high level message to the user with timestamp (server side timestamp). Issue can then be investigated by reading logs.
BPM Enablement CTS Version (TIBCO) 63
TIBCO AMX BPM Best Practices
Sub processes Use process interface for sub processes that will probably change in the future.
Process interface establishes a contract between parent and subprocess. It is mandatory for dynamic subprocesses but also interesting for subprocesses that can change.
Why
simplify process migration increase reusability & exchangeability
Separate process interfaces of sub processes in other (extra) BS Projects.
This will decuple dynamic subprocesses at runtime and allows deployment of subparts without affecting the main procedures. (“getting out of sync.”)
Why
simplify deployment increase flexibility
Interfaces & independent Subprocess deployment
Split against following rules:
‐ Separate different Business Areas
‐ Separate different Backends
‐ Separate different topics i.e. Credit, Check, Contract, etc.
‐ Reuse for different Main Procedures
‐ Reuse BOMs where Possible
Benefit, separaon simplifies:
‐ Working in a Team, especially XPDLs
‐ Deployment of Projects
‐ Subprocedures can be deployed independently.
‐ Faster Deployment of Updates
‐ Faster Node startup
... and it add‘s flexibility!
Service process & Service Process Interface
As of AMXBPM 4.0, there is “service process”, which is a stateless process that is not audited or persisted, but is far more performant. It can be called from Business Process or a pageflow.
Used in Business Process, they should be defined in an external project, so that it can be updated independently of the business process
BPM Enablement CTS Version (TIBCO) 64
TIBCO AMX BPM Best Practices
How To:
The example below illustrates how to call a pageflow, but works the same for sub process
1. create Sub procedures using Process Interface Projects
2. Use a Runme Idenfier Field to specify the Process Path
Inial value is build this way : / ProjectName /Process Packages/ xpdlFileName.xpdl . processName where ProjectName is the name of the project containing the pageflow we want to call. An easy way to get the highlighted part is to right click the XPDL file of the project that contains the sub‐pageflow and copy the “path” of the “resource” tab.
BPM Enablement CTS Version (TIBCO) 65
TIBCO AMX BPM Best Practices
3. Use Inial Value to configure Process Path 4. Use for every Subprocess another Runme Idenfier Field 5. Store Process Interface, Subprocess, and Main Process into different Projects
(So there is at least 3 BS Projects)
Use mapping script rather than in the Iniate script for sub‐processes.
If used in as a MultiInstance reusable subprocess, the init script may not behave as expected (for example the Process.getActivityLoopIndex() will not get the correct data for each instance
Why
using a mapping script will guarantee the correct evaluation in MultiInstance Loops of local variables.
Use Data Mapper
As of 4.0, the Data Mapper has been added in Business Studio in the following places:
Process Manager Scripts Script Tasks Rest activity Sub process Web Service Error Handling
The Data Mapper can be used as follow:
BPM Enablement CTS Version (TIBCO) 66
TIBCO AMX BPM Best Practices
Simple mapping (object type A to Object type A) Heterogeneous mapping: object type A to object type B, with A & B sharing several
attributes name: Map A to B, right click on the link, and click “Map likeNamed child content” option.
Make some mapping, switch from “Data Mapper” to Javascript: you’ll get the javascript corresponding to the mapping you’ve one. Javascript check for null values, iterate over arrays. This is a good way to speed up javascript writing with complex objects.
On a script task, use the mapper on the general tab to make a basic mapping, and use the scripts tab to make some small update. Let’s say you need to have a copy of an object with many fields, except for a few attributes. You can use the general tab/mapper to make the basic mapping, and then use the script tab to modify a few of these attributes.
BPM Enablement CTS Version (TIBCO) 67
TIBCO AMX BPM Best Practices
Web Service Integration Use a Service Layer to define services used by the BPM.
Create a project containing the WSDL used by the processes. When possible create those WSDL in Business studio from a BOM.
Why
Use “Business Oriented” services containing the same concepts (classes) as your process. Ease the mapping at BPM level.
Be sure to use schemas supported by AMX BPM (WSDL created from a BOM is supported, imported WSDL may contain unsupported elements).
Use a Service Layer to define services used by the BPM.
Contract First approach : to be able to upgrade process with interface change
If you expose your Business Process as web services (PaaS: Process as a Service), you must implement it with the contract first approach. This is a best practice of the SOA world. If you’re exposing as WebService, you should follow the SOA best practices. See this LBN for more details LBN 36616: https://support.tibco.com/sst/index.jsp?mode=get&id=/ka/000/36616.htm By default, BS is producing the WSDL from the project BOM: it’s Contract Last approach (you elaborate the contract (WSDL) from the implementation. The problem with this approach is that:
If you need to make non compatible changes to your WSDL (adding a mandatory field, remove a field) : you won’t be able to do this unless you rename your project, which will generate other issue.
Some compatible change in your WSDL may not be detected as compatible (product limitation), such as “increase the length of an existing data field)
To implement Contract First approach:
In your development cycle, wait that you’re fairly advanced/stable in your interface The Data
Create a new project of type “Business Object Project”, use the name of the project and append “.bom.v1”. Update the project ID in the lifecycle tab of project properties
Copy Paste the classes to be used in the interface in this new project. If a class reference another, update the references.
If you want to pass multiple classes to your BPM project, you need one object to encapsulate them to be WSI compliant.
Name this object like : Start CreateBankAccount V1 If you need to return the process instance Id, create a “Return” class that will hold
the pvmId On your process BOM, right click export => “XML Schema” In the exported xsd, replace the “tns1” prefix by your own prefix, as tns1 will
To avoid conflict later, replace double_StudioGeneratedTemplate by double_BPM
The WSDL Create a new project of type “BPM Project” use the name of the project and append “.wsdl”. Update the project ID in the
lifecycle tab of project properties On the “Asset Type Selection” uncheck everything but “Service Descriptor” Right click on service descriptor, NEW, WSDL File
Name: StartCreateBankAccountV1.WSDL” Replace the TargetNamespace org.example by the client company name
reversed. Remove existing operations & parameters Create a new operation “StartCreateBankAccountV1” Copy the XSD of the previous project in the WSDL project, close all other projects.
(you’ll get duplicate object error, that’s why you need to close at least the previous BOM project, and do a “clean all”)
Add parameters IN/Out and choose the appropriate Element. Be careful to pick the correct class in the WSDL project
Replace the prefix by the one you’ve chosen Check that there’s no error
Import the WSDL in the BPM project Copy the WSDL and XSD in the “Service Descriptor” folder in the BPM project. Close the BOM & WSDL projects, clean all (to remove generated classes that
cause duplicates errors) In the BPM Process, change the trigger type of the “start” for the “Message” Type Click Select and choose your V1 operation, check the “Reply immediately with
process id” Rename your start to V1 Create a Parameter datafield of the type from your XSD
(Start CreateBankAccount V1) In the start process, map data to your parameter IN/OUT In a script task or “complete script” of the start task, use the data mapper to map
objects from the parameter type, to the internal bom. You’ll get an error, right click on the link “Map likenamed child content”
It’s mandatory that parameters are not used anywhere else in the project, or it will ruin what we’re doing.
⇒ You’re now able to start your BPM project with an operation and class that is not tied to the process implementation
Implement a process interface change Copy Paste your existing XSD/WSDL Change the namespace to V2 Change the operation and the Start Object to V2 Add a new Catch Message, name it V2, select the
V2 operation, add a V2 parameter, copy/paste the script that map parameter to internal BOM
If you want the V1 path to be still accessible, let it connected to the process, otherwise generate a workitem to an admin so that he is aware there’s still a component in the entreprise that use the old process definition.
BPM Enablement CTS Version (TIBCO) 69
TIBCO AMX BPM Best Practices
Use a BusinessWorks Layer between BPM & SOA
Business Works is TIBCO integraon tool. It’s far more powerful than mediaon for this job (or plain java code)
Loose coupling between BPM and the rest of the world
You must not call business services directly (for example the service that create a contract in AS400).
The reason is that any services outside of AMXBPM can evolve at a different pace than your BPM projects. If there’s a contract change in the service, you’ll have thousands of process instance that will at some point call this service and fail. You’ll need to redeploy a new version of your BPM project urgently, retest, and try to migrate process instances. And in some cases, migraon is not possible (if your service call is in a parallel path).
While with a BW project, it’s rather simple to redeploy a new version that will take care of the the service interface change: you don’t have live process instance to migrate in BW.
BW project owned by the BPM Project team
The BPM project must own the BW project that make this interface with the rest of the world (even if the ESB is done in BW). The BPM Project team must not struggle for resource that is not in their team.
Very Simple BPM to BW interface
Also, ideally, your BPM to BW interface will be minimalist :
External DB ID (id you use an external DB to store all data) Or CaseManagement Ref A verb : what I want to do BPM id (pvm id): mainly for logging purpose. Business ID: for logging purpose
BW will first fetch all data, and with the “verb” (ex: create contract) will know what to do.
With the minimalist BPM to BW interface, you’re very unlikely to have to change this interface.
With BW fetching all data : it has all informaon required to make any service call.
BW project is very useful in many aspects
When building a BPM project, you will need to a BW project for:
Implemenng some technical stuff that are related to your project (sending formaed email to customer, sync BPM user with correct posion/capabilies etc…)
Call BPM on some event, expose those event to the rest of the world, with throling feature so that BPM is not hammered.
BPM Enablement CTS Version (TIBCO) 70
TIBCO AMX BPM Best Practices
Subscribe to EC Topic to perform technical stuff. (Status update, logging)
Once you have BW in your project you have flexibility to do anything.
If you don’t have BW license, that’s very sad, but still you should use a J2EE/.Net/any tech layer to implement the same things as above, and in last resort use a Mediation (which will only cover a part of above)
Front End Integration options
AMXBPM offers several front‐end opon:
Use Out of the box openspace/workspace web application: Most of the features are available, not the most user friendly way, but that’s the only way to cover everything. There’s some customization possible on openspace/workspace, but don’t expect miracles.
Use App Dev feature to build a custom UI hosted on AMXBPM, build with AngularJS technology, using OOTB angular service and directive. You really can build a custom UI within AMXBPM. You’ll probably need some services of your enterprise exposed has rest, and use a reverse proxy to avoid the “sameorigin policy” browser restriction
Use a custom front end (J2EE/.NET), where every component is written from scratch (work list, display a form), and the front end interact with AMXBPM through web service API
Use a custom front end (J2EE/.NET) where most of the component are written from scratch, but use Business Studio forms (using a specific set of API + formclient.js)
Which option to choose?
If you’re in hurry to deploy a process very quickly, use OOTB openspace or the sample “MyWorkApp” form appDev, and develop very low complex forms within business studio.
If your company has UI framework to display data, elaborate complex object, it’s very unlikely to be embeddable in forms with Custom Control, so go for Custom UI.
If you have a lot of forms to implement but no skills in BPM forms and short time to implement, go to custom UI. It’s the safest approach to have a successful implementation as you know how much time your dev team will take to implement them.
The more complex you form are, the more you want to go to Custom UI, as you’ve more freedom to do whatever you want.
Using Custom UI, you’ll need to handle object serialization with JAXB, handle the workflow patterns (chaining in business process, pageflow etc…)
Depending on your company security scheme, you may not be able to use openspace/workspace. I’ve seen several company that use nonstandard authentication method to cover complex requirements (multicompany, capability/authorization enabled solution)
You can use a mix of the two last option: use BS form for low to medium forms complexity, use custom forms for more complex form. Use the Activity Name to know which one to use (Naming convention or configuration in the custom UI)
Notice that you can build your own UI component to be used/reused in Business Studio forms using Custom Control. For example, you can include a Gant Chart, pie chart, gallery of image to choose a product etc… Having a custom control make this UI component reusable in several user tasks.
BPM Enablement CTS Version (TIBCO) 71
TIBCO AMX BPM Best Practices
You can use the AngularJS rest API, Directive & Services in a Custom App, but beware that you’ll be tied to the AngularJS Version shipped with AMXBPM and that evolves with HF. So applying an HF to fix a process related issue, may have side effects on UI if AngularJS version is upgraded. Having two version of AngularJS 1.x is difficult (can’t use JSONP). Maybe it’s more easy to combine Angular 2.x and 1.x.
BPM Enablement CTS Version (TIBCO) 72
TIBCO AMX BPM Best Practices
Exception Handling When possible, do “read” service call in User Acvity page flow.
Doing so, you can warn the user doing the task about the service issue and propose some solution. For example, he may close the current task and retry later.
However, this approach cannot be done on all service invocation (some service calls are not related to a user activity and have no meaning for the user).
“Write service call” that fails
At some point towards the end of a BPM process you will want to perform a “write” service call to concretize the outcome of your BPM Process, like creating an insurance contract in the AS400.
It is important that this activity that is the achievement of your BPM Process is in the main Business Process and audited.
Most of the time, you don’t want to use “Catch Error” on those service task, but use the API below.
In some specific case, you may want to use some custom retry mechanism (ex: retry 5 times, 1 days between each time, do some custom logging, and at the end have a workitem for a sys admin). In this case, take really good care of forwarding all the error information without any loss, to help the investigation.
It’s important that when these service call fails, you’re alerted that process instance are in failed state so that it can be taken care of (instead of just having a stack trace in some logs, or nothing at all if you do this in a pageflow/Service process)
AMXBPM offers OOTB feature to cope with failing service call in Business Process.
You can, with an user that have the “ haltedProcessAdministration” privilège
Query Process Instance in Failed State : (available in openspace/workspace) https://docs.tibco.com/pub/amxbpm/4.1.0/doc/html/bpmhelp/GUID4105F9951E2
This should be part of a monitoring of the platform ! setAvailableProcessInstanceVariables : update the data of a failed process instance. If
your service call fails because of data related issue (data missing, incorrect, corrupted), this is the way to solve the issue and then call the retry Process Instance
Use getAvailableProcessInstanceVariables to know which variable are available https://docs.tibco.com/pub/amxbpm/4.1.0/doc/html/bpmhelp/GUIDE75C0063D04
A42DA88756E4D187E0D5D.html None of the two above methods are available in workspace/openspace.
Resume the process Instance(s) : it will resume the Halted process in its current state (failed), and then go to failed state (instead of Halted that prevent the instance deletion) and be removed from the system. Useful when the error cannot be recovered and we need to clean up the system. If cleanup is not done, there will be halted process instance on some version of the process, and AMXBPM won’t be able to undeploy the process (after new version has been deployed, and all other running processes have completed) (available in openspace/workspace)
Ignore the service call and resume the process(es) (available in openspace/workspace) https://docs.tibco.com/pub/amxbpm/4.1.0/doc/html/bpmhelp/GUID48B3676F63E
24E13B68C0B445B4282EB.html
Create reusable sub‐process for generic service task error handling.
Catch Service Task Errors with Catch Intermediate Event and send context to an error handling subprocess. An operator (organisation to define) may decide on 2 options : continue (the problem has been solved in backend system), retry (for ex: network problem solved). The ability to change business data has to be decided by governance rules.
Use a custom soap fault to provide resolver user with pernent informaon.
Error Catch event has a “Map Error” configuration. On a default Soap fault, you will get only a useless stack trace with internal BPM error during the web Service call. Catch a custom fault to get the custom fault schema and map the correct information to your process.
Handle technical excepon: not available, meout, soap parsing error.
In case of technical fault, you will not receive a custom fault. You have to handle those cases with a catch All.
Refer to “AMX BPM Service integration Error Catching and Troubleshooting” doc to get details on Error Handling.
Testing Set up Emulaon files to cover the different ways of going through your process (all possible use cases) . Studio offer a batch testing feature to start process instances based on emulation files. Learn and use this feature. Emulation files can mock user tasks and service tasks that are not yet implemented/available by providing only the expected output of these tasks Targeting for debugging, they are also convenient for testing that all your scenarios leads to completed process instances.
(Note : Emulation of UserTask, subprocesses, service task is not working in 2.0)
Create mocks for integraon services and save your mocks in the source control as they are precious asset of your project. Use external tools like SOAP UI to mock services used by your process. You can record real responses on external systems and use them in the mock responses or build responses from scratch. SOAP UI allows you to create complex response strategies (based on incoming data). Having a good mock repository will certainly speed up your developement.
Debug/Tesng When deploying processes to testing, turn on TIBCO DEBUG via eclipse preferences. This will allow you to use debugger to step through process and page flow.
Don't connect to a customer's test node whilst testers are working to watch/monitor what they are testing you will like cause issues and at best cause confusion with error messages in log files.
It’s because tester will be stuck on your breakpoint without understanding why. You should have a dedicated AMXBPM environment to do this (check the Development server that comes with its own PostgreSQL DB and LDAP) Plan to use emulation feature of AMX BPM and build/plan tests and regression tests. This will significantly reduce testing effort and reduce reliance on business testers.
Testing is by a nature a massive cost for a BPM project often involving lots of people/systems with specialist domain knowledge. The testing features of AMX BPM are a massive benefit/differentiator.
You may also want to use tools like SOAPUI or BW to start BPM Process instances with specific set of data so that you have process instance ready to test. Use a field to identify the test scenario. (ex: Business Customer ID : TSTSCNA) You may also want to have workitem completed automatically so that you have a pool of workitems available at various point of your process. Like this your tester do not have to start from scratch (start process instance, complete each workitem until the test point) Testing involves:
Form testing in Business Studio (with Custom Data capability). White box testing of process with Debugger and emulation files to simulate user activity Black box testing with external tools (soapui, …) Page flow testing Performance testing Administration operation testing (scripts).
BPM Enablement CTS Version (TIBCO) 75
TIBCO AMX BPM Best Practices
AMX BPM Reporting best practices AMX BPM uses TIBCO Spotfire module for reporting, based on Event Collector data.
As of AMXBPM 3.1 you can also use TIBCO Jasper Reports professionnal (licence included with AMXBPM).
As of AXBPM 4.1, API has been added/redesigned so that audit informations are get as tabular data to be displayed with HighCharts JS library. You’ll have less possibility than with Spotfire/JasperReport.
Spotfire is the best option, from an end user point of view, this tool is very powerfull!
Extend reporng with Business Data
Reporting is based on EC tables which do not include business data. Create a custom database for reporting on the business data and join with the EC tables based on process instance ID.
Business Data table can be filled by
a custom code before starting a process (in that case, design your process to return synchronously the process instance id. The caller can store it for future join).
A service call in the process to explicitly store a business data. A listener on the EC module to detect process starts event and a call to the AMX BPM API to
query the process instance parameters or data fields. Usage of AMX BPM 3.x Global Data Object Tables
Configure wi aribute auding to create reports on work items with business meaning. Workitems attributes (14 until 2.2, and 40 after) are initially designed so that, on the work list, the user can know on what work item he is clicking on, can sort and filter the worklist. These attributes are often very business specific and have a big value for reporting.
If you’re using an external database to store business data, you probably want to use attribute1 (integer) to store the primary key of the main table of this external database.
Refer to the admin guide §"Auditing Custom Work Item Attributes" to configure your system to audit attributes (you can specify which attribute to publish and on which work lifecycle event).
Once configured, attributes are stored in ec_wi_status table for reporting.
Reporng You must consider reporting/process visibility from the start it will influence process design.
Make sure your tasks "live" for appropriate time to aid reporting. ie. don't keep recreating same task (a common bad pattern to update attributes).
BOM Class data are stored as serialized XML within AMXBPM Database, which make it improper for reporting.
Consider to use :
Global Data (each Global Class are stored as a specific table) External Database Workitem Attributes
BPM Enablement CTS Version (TIBCO) 76
TIBCO AMX BPM Best Practices
You can also use custom event messages to post data to event collector. You can add custom event using the API or javascript within the BPM Process: “Process.auditLog(String)”
You can use a “Task” as a milestone in process to aid reporting example, if you need to measure SLA from stage 1 to 2. Then perhaps stage 1 or 2 milestone should be easily identifiable in process and therefore event collector.
A task will not block the Process execution, but will be audited.
BPM Enablement CTS Version (TIBCO) 77
TIBCO AMX BPM Best Practices
AMX BPM Operation best practices
Obfuscate (crypt) password in configuraon files Some configuration files, or ant script may contains some password. It’s better to obfuscate this password. You need to install ant (The ant in amx/3.3/bin Doesn't work, complains it doesn’t found tools.jar) . (I use the 1.10.0) vi /tibco/amxbpm/binaries/administrator/3.3/samples/ adminscriptsbase.xml replace @@TIBCO_HOME@@ by the correct path : <property name="tibco.home" location=" /tibco/amxbpm/binaries " /> And then it works: [tibco@centos6 apacheant/bin]$ ./ant f /tibco/amxbpm/binaries/administrator/3.3/samples/obfuscate_build.xml Dpassword= mypass Buildfile: /tibco/amxbpm/binaries/administrator/3.3/samples/obfuscate_build.xml inputpassword: encrypt: [AMXObfuscateTask] 12 Jan 2017 15:30:37 INFO Initializing JSSE's crypto provider class com.sun.net.ssl.internal.ssl.Provider in default mode [AMXObfuscateTask] Obfuscated value:[ #!crOMQ7i3mhsU2CnOBSphaqTMe2XvLQWJ ] BUILD SUCCESSFUL
Starng and stop On windows, you can register Nodes (System or BPM) as a Windows Service.
BPMNodes can be started without having the Administrator running (in this case, BPM is running normally, you just can’t upgrade or modify the BPM Processes).
On a multinode installation, Stopping AMX Administrator will not impact the BPM operations. https://docs.tibco.com/pub/amxbpm/4.1.0/doc/html/bpmhelp/GUID8C919ABD3B5E45E7B539FCE6DC37C48A.html
Starting : cd /tibco/amxbpm/conf/tibcohost/AdminAMXBPMAMXBPMServer/host/bin
./tibcohost spawn
Is equivalent to : nohup ./tibcohost start &
Stopping : cd /tibco/amxbpm/conf/tibcohost/AdminAMXBPMAMXBPMServer/host/bin
Producon Stop/Start : In production, you want to archive your logs (hosts and nodes), so that on each startup you have the logs from the current start.
It will make the logs for more easy to navigate (smaller files), grep for errors, or send to support for analysis (it will cover only the time frame from last startup)
In development : Include HouseKeeping in your start and stop scripts In Dev you may add some housekeeping in the start script like deleting logs and EC tables :
del /S C:\ProgramData\amxbpm\tibco\data\tibcohost\*.log
call purgeEC.bat
cd C:\ProgramData\amxbpm\tibco\data\tibcohost\AdminAMX BPMAMX BPM Server\host\bin
tibcohost.exe spawn
purgeEC.bat is a simple sql command (here for Microsoft SQL Server) :
You must install purge stored procedure : refer to Admin Guide, "Clearing Audit Entries and Statistical Data”. https://docs.tibco.com/pub/amxbpm/4.1.0/doc/html/bpmhelp/GUID0897537E2EC449B694946D4B75A457AF.html
Personnalize AMX Adminsitrator to differenate Prod from Non Prod environment
Since AMX 3.3.0 HF10, it’s possible to lightly customize the login page of AMX Administrator, and the header of the administrator once connected. This allow to differentiate production and nonproduction environment. To make this customization, you need to edit the SystemNode.tra and restart the Node SystemNode.tra, before the block of text containing "# DO NOT modify beyond this line." #AMX Admin personnalization java.property.com.tibco.admin.gui.login.screen.banner.text=PRODUCTION Platform java.property.com.tibco.admin.gui.login.screen.banner.text.fontColor=red java.property.com.tibco.admin.gui.topPanel.banner.text=PRODUCTION Plateform Restart the SystemNode : ./tibcohost stopNodes nodeName SystemNode ./tibcohost startNodes nodeName SystemNode The official documentation is on the HF10 description: TAP14120 With this TIBCO ActiveMatrix Administrator enhancement, the user will now be able to add a Banner and change its color in the Administrator Login page by adding the System properties "com.tibco.admin.gui.login.screen.banner.text" and "com.tibco.admin.gui.login.screen.banner.text.fontColor" respectively, as shown below, in the SystemNode.tra file: java.property.com.tibco.admin.gui.login.screen.banner.text= <Banner Text, for e.g. "UAT Enterprise"> java.property.com.tibco.admin.gui.login.screen.banner.text.fontColor= <RGB, HEX or HTML Color Name, for e.g. "red" or "#FF0000"> The user can also add a Banner to the Navigation page by adding the System property "com.tibco.admin.gui.topPanel.banner.text" with custom text as shown below, in the SystemNode.tra file: java.property.com.tibco.admin.gui.topPanel.banner.text= <Navigation Banner Text, for e.g. "ActiveMatrix Home"> Both Banner texts, if not configured explicitly with System properties, currently display the name of the TIBCO Enterprise specified in the TIBCO Configuration Tool during Enterprise creation. The maximum length of each of these Banners is set to 80 characters, after which they will be truncated and the complete text will be displayed via a mouseover HTML Tooltip.
Low entropy on linux machines On linux, /dev/random is using physical IRQ to get some random data and generate random
BPM Enablement CTS Version (TIBCO) 80
TIBCO AMX BPM Best Practices
number. It’s very important as this random generator is used for SSL and also by Oracle JDBC Driver (even without ssl connection to the db). On linux running on VMWare, there’s no physical port and so the entropy is low. [tibco@centos6 tibco]$ sudo /sbin/sysctl A | grep random [sudo] password for tibco: kernel.random.poolsize = 4096 kernel.random.entropy_avail = 137 kernel.random.read_wakeup_threshold = 64 kernel.random.write_wakeup_threshold = 128 kernel.random.boot_id = d081bcb4558d4e0da355eefd6bb9be81 kernel.random.uuid = e54e4af4a5bc4727ada0f706e096b8e8 kernel.randomize_va_space = 2 [tibco@centos6 tibco]$
The value is low when entropy_avail <<< poolsize (as in the example above). This can lead to AMXBPM Slowdown or even JDBC communication error, as the random generator waits to have sufficient noise data to produce random numbers. That’s why you can experience about 1 minute pause on AMXBPM Startup or even errors on Oralce SQL Queries. To overcome this issue, we can change the file used to generated random numbers Edit $JAVA_HOME/jre/lib/security/java.security and replace securerandom.source with securerandom.source=file:/dev/ ./ u random
VMWare resources The install documentation states that you need the following resource available to be supported: https://docs.tibco.com/pub/amxbpm/4.1.0/TIB_amxbpm_4.1.0_readme.txt ====================================================================== Minimum Hardware Requirements Disk Space: 5 GB of free space on the local drive where you are installing TIBCO ActiveMatrix BPM. Memory: Two 3 GHz dual processors with 8 GB RAM. 8 GB of virtual memory available for user applications. ====================================================================== On VMWare, you can share CPU & Memory. This can have significant performance impact on AMXBPM, resource should be dedicated not shared (and especially you should ensure that the above minimal requirements are met).
Monitor the DB performances with AWR Stats on Oracle and check that the DB is not spending too much on waiting for I/O.
Use nodeUtil to find dependencies issues on your system: https://docs.tibco.com/pub/amxbpm/4.1.0/doc/html/bpmhelp/GUIDF390592F7BC8460E9BD3C6542A10BB65.html [tibco@viramx04ppr bin]$ ./nodeutil Invoking commandLoop AMX nodeutil 1.8.0 command loop. Type "exit" to leave the command loop. Type "help" for a list of available commands. Type "help" <command> for help on a particular command. WARNING: The node must be shutdown before running this tool. Not doing so may cause severe error. This command does NOT verify that the node is shutdown. WARNING: TIBCOAMXTOOLSNODEUTIL000002: The command loop was not completely configured. Some commands will not work without additional arguments. > updateDependencies dryRun configFile nodeutil.cfg Updating following components on node "BPMServ2Node1" from application "*" with version "*" (dryrun) >
Monitor the various pool of resources of each Node : ./tibcohost describeDeployedResourcePools nodeName $CURRENT_NODE_NAME outputFormat detail
Create Drop Script for any custom index you’re creang Adding custom index on AMXBPM DB should be done by opening an SR to get Support Approval, create the create scripts and the drop scripts
Not dropping the custom index will make any upgrade fails.
Audit log Define an audit strategy and configure EC publicaon and loggers
You can control what is logged on the log files, what is logged to the amxbpm database, and what is published on the EMS EC_TOPIC.
On big AMXBPM system, you may want to not log some event to the database to lower the load on the DB (in particular, the disk space). Doing so, you will loose information on the process, so make you choice carefully, as the audit log is important for reporting, and production issue solving.
Also, one common pattern used in AMXBPM with an external DB for business data is using the Event Collector publishing on EMS:
To avoid having a WebSerivce (or worse (because of high coupling), JDBC) activity after each user task to update the state of the business object, we use AMXBPM publishing on EMS to publish the “BRM_WORKITEM_EX_COMPLETE_WORK_ITEM” audit message that is published when a workitem is completed. A component (BW engine, or Java custom code), is then listening on the EC_TOPIC (or more likely a bridged queue in a Highly Available system) to consume the message and update the external DB.
Note that : ecproberules.xml & eceventrules.xml are periodically read by AMXBPM, so that you don’t need to restart AMXBPM so that changes you’ve just made are taken into account.
The logging level of amx.bpm.app configuration is described here: amx.bpm.app application logger and appenders : refer to “Defining Logging Information” in AMX BPM Admin Guide. https://docs.tibco.com/pub/amxbpm/4.1.0/doc/html/bpmhelp/GUID5ADC9B65EA8E4E469C893CD402B73D06.html
Archive and purge Setup Event Collector purge.
AMXBPM is purging data of process instance once they complete or fails (if halted, data is not removed so you can retry the failing activity).
The Event Collector however is not purged, so that you can retrieve the audit data of each instances.
The Event Collector is quite verbose in term of auditing so that you can have the most accurate vision of what happened. But this come with a cost in term of storage and performance on the Database Side.
To keep the AMXBPM System running at a constant state of performance, it is necessary to perform purge of the event collector.
Activating the purge should be done as soon as AMXBPM is used in production.
Before purging you may want to setup some kind of replication of the Event Collector table content (with the publishing feature on EMS for example).
On BIG AMXBPM System, you may want to keep only 3 months of Data in the Event Collector.
This can have a side effect on reporting (since you’re removing data from EC that is used by Spotfire)
Refer to “Housekeeping Tasks” in AMX BPM Admin guide: https://docs.tibco.com/pub/amxbpm/4.1.0/doc/html/bpmhelp/GUID82EED0F0037E48C99D8EC5FE2B05E9F8.html
An easy way to purge is to use EventCollectorManagementService doPurgeAudit. The other way is to use the Store Procedure.
You need to install them, and run it. The advantage of using them, is that you can control
when it’s executed the number of parallel thread that are running to make it more efficient. The commit size (number of rows deleted in one transaction)
For example, during production hours, you can have a single thread continuously purging, and during non production time, have several threads, which will use the full available power of the database.
It works has follow Run create_purge_sessions stored procedure, with a date before which it
will identify the rows to delete, and the number of session to create for those lines. Each lines to be deleted will be associated a session number between 0 and the number of session.
Run start_purge_session with a session ID (with the same range as above) and the commit size. This should be run as shell background job and in parallel
With this approach, the config file does not include the version and the DAA will be uploaded at each deployment.
You can directly use those scripts using the CLI (Command line interface) or in Studio (right click on the script config (xml file) and select ‘run as ant script’.
In a large project, you will have to deploy several applications. You should use those scripts as a starting point to create your project scripts (deploying a group of applications, checking deployed application on a server, …).
Refer to AMX BPM html documentation to learn the CLI.
TIBCO Active Matrix BPM / Administration / SOA Administration / Administrator Interface / CommandLine interface.
Set “deploy project” and use them as soon as possible in the project
In Business Studio, you can create a “deploy project” and list all BPM projects to be deployed as a consistent solution.
> Refer to “deploy project” feature.
Do not make BPM Applicaons part of SOA Service deployments
BPM Applications have a different Lifecycle, than SOA Service. Also they have outstanding process instance that will prevent the application from being undeployed (the status will be preparing for undeploy).
In Production, Outstanding process instances are removed by :
Being completed to the end Being migrated : Migrating process instances requires
a good design of the BPM process to have the maximum of migration points a complete testing before doing it in production (complete the migrated instance to
the end to ensure it won’t fail, for example if you introduce a new mandatory field that will be empty).
Use a “dev mode” deployment script to delete and deploy
During development, you probably deploy several times the same process application with changes that are not suitable for an upgrade: process interface change.
Create a script that will undeploy, delete existing application and deploy and start the new one. Note that running process instances must be cancelled , this can be automated using the BPM API.
Generate the DAA, then generate CLI script.
BPM Enablement CTS Version (TIBCO) 86
TIBCO AMX BPM Best Practices
Select UnDeploy and Delete.
Continue deployment configuration, and don’t select upgrade (it is selected if your application is already present on the target server, if so unselect it).
Open <project>.deploymentconfig.xml file. It contains a line for the application template :
< ApplicationTemplate xsi:type = " amxdata_reference:ApplicationTemplate_reference " name = "TIBCO.sample.migrationstarter" version = "1.0.0.201203061712" /> Remove the version attribute :
< ApplicationTemplate xsi:type = " amxdata_reference:ApplicationTemplate_reference " name = "TIBCO.sample.migrationstarter" /> So that your script will now run for any generated DAA !
Open <project>.deploymentbuild.xml
It contains instructions to upload the DAA , change the overwrite, merge option and failOnError.
<!‐‐ Upload DAA specified in the data file ‐‐> <target name= "upload.daa" descripon= "Uploading Applicaon" > <AMXAdminTask
</target> Else, when you deploy a DAA without changing the version, the script would just create an application based on the old template already uploaded. In this dev script we want to force deployment even if the version number is the same.
BPM Enablement CTS Version (TIBCO) 87
TIBCO AMX BPM Best Practices
BPM Enablement CTS Version (TIBCO) 88
TIBCO AMX BPM Best Practices
Project upgrade and migration When a process is upgraded, the existing process instance continue to execute in their current version until it complete the process definition, they are not automatically upgraded. Old version of a process are not startable anymore.
Old process instance can be migrated to newer version of the process definition by setting a rule in Openspace to migrate the old process instance to the new version at specific migration point.
It’s useful to migrate old process instance so that :
Instances of the old version of the process can benefit from the new implementation. Old version of the process can be undeployed and deleted (which lower the resources usages on
AMXBPM)
In some business case, you may not want to migrate process instances, if for example, your BPM process implement some legal rules, and that all process instances before a legal rule change must still apply the old rule.
Design for having migraon points
An activity is marked as a potential migration point with a grey icon in the upper left corner:
There are some constraints for defining migration points, here are the major ones:
A process must have at least one migration point (this can be disabled with the quickfix, but you should do so only for very short lived bpm process)
activity must have a name the name must be the same between the old version and the new version of the process not be in a parallel path The migration happens when the process arrive on an activity. This means that workitems that are
in a user task when the migration rule is activated won’t be migrated until they reach the next migration point.
The complete list of restrictions is available in the “Modeling” guide, “Migration Point Restriction” chapter. https://docs.tibco.com/pub/amxbpm/4.1.0/doc/html/bpmhelp/GUID21677DBA3A0649A6B415DB4335ED84A9.html
Check those constraints in the documentation and design the process to control your migration points. Test can only be done by deploying and upgrading, as migration point definition is not done at design in Studio but in OpenSpace at runtime.
The best practice is to have a copy of the exiting production and run the migration test on it.
Ancipate process instance recovery “GOTO” points.
In some case, you may want to start new instances with old data (migration from non TIBCO solution case or disaster recovery strategy). The engine does not support “GOTO” notion, but you
can define multiple starting points in your process. Doing so you can allow starting instances at different points that will be exposed as operations in the process WSDL. (Obviously you have to build an injector batch using the exposed service operations).
Downgrading applicaons
Downgrading a BPM application to an older version should be avoided. Instead create a new DAA from the old source project and deploy as an upgrade. Prior to AMX BPM 2.0 it was possible to downgrade to a version of an application that had running instances (undeploying) this would break the node. In AMX BPM 2.0 downgrading to a version of an application that has running instances is disabled by admin. Downgrading is possible if application has undeployed the old version. Even with AMX:BPM 2.0+ QA still recommend always taking old source and creating new DAA rather than downgrade. Soware Management To keep disk space smaller and to keep the Environments clean, older unused Project Templates should be deleted from any installation. Use AMX Administrator Options, under Infrastructure → Software Management:
You can see if a DAA, Feature or Application template is in use or not. If not in use, you can safely delete it. You can select multiple item at a time and delete it in one click. If you delete DAA, associated Features & Application template will be deleted as well. If you delete all Features & Application template that comes with one DAA, this one is deleted.
Removing applicaon templates with CLI: Application Templates can take up a lot of disk space on development systems where you frequently upgrade/replace apps. You can remove them from the UI, but its better to remove them via CLI if you have a lot:
BPM Enablement CTS Version (TIBCO) 90
TIBCO AMX BPM Best Practices
ant –f application_build.xml remove.template This command needs to be run from the folder where you have the application_build.xml and application_data.xml file. By default in your AMX installation these scripts are located in [TIBCO_HOME]\administrator\3.2\samples The build file refers to the data file that has all data about your app templates. You will need to add the names of the app templates and versions in the application_data.xml file. <AppTemplate xsi:type="amxdata_base:AppTemplateID" name="testApp" version="1.0.0"/> Also you need to modify the remote_props.properties file in the [TIBCO_HOME]\administrator\3.2\samples folder since it is referred by the build file.
User Management Use mulple LDAP Containers for more than 1000 Users
In current AMX BPM 2.2. to many Users in one LDAP Container slows down the UserManagement i.e. in Workspace. At runtime there is no Issue. i.e. splitt all Users in alphabetic groups, or for multiple Business Units No Issue in AMX BPM > v3.x as Openspace Org.Browser comes with pagination feature and quicker resource browse feature. use BW to sync. your LDAP Users with the Org‐Model
In many Projects a BW Job is used to sync the Users of LDAP or a HR System with the AMX BPM OrgModel on a daily bases, instead of a manual task. User removal
If you remove a resource who has process instance those instances will fail.
The best practice is to remove/disable the user in the LDAP but leave it in AMXBPM: Authentication of this user will fail, but process instances started by this user will remain active until completion.
if you must remove resources wire to process starter over HTTP and use static username/password policy or governance application to switch user ID.
or build custom java composite to switch user ID
BPM Enablement CTS Version (TIBCO) 91
TIBCO AMX BPM Best Practices
Performance Tuning Best practices Performance Tuning is not only about CPU’s & Memory
Limit the number of activity on the Happy Path of a process Consider the example below, in the first version the gateway is not necessary and
generates 2 entries in the Event Collector and requires PE Thread time. The second implementation behave the same way, but do not use the gateway.
⇒ Gateways Consider whether the gateways in the process are actually required.
For example, a parallel split gateway may not actually be needed and can be replaced by just having two paths running directly from the task:
In high load situation, do not use sub process if you want higher performances.
It’s a trade between design/reusability vs performances, but reimplementing changes is rather quick and cost little money versus a low performance implementation which impact the business every day. The process below is called 4 times in the main process definition that is instantiated about 40’000 time a day, and also in all other processes. ⇒ This mean that optimization will have a significant effect on the production.
Non optimized version produce 39 lines in EC_EVENT with 17 artifacts. Optimized version produce 12 lines in EC_EVENT ⇒ 70% of gain
with 6 artifacts ⇒ 64% of gain. BPM Enablement CTS Version (TIBCO) 92
Non optimized version: it uses gateway, script tasks, sub process.
The sub process:
The optimized version: It has one gateway and two service task on the happy path, it use a different exception model for functional error to avoid a gateway (and a cleaner implementation)
BPM Enablement CTS Version (TIBCO) 93
TIBCO AMX BPM Best Practices
Limit the amount of data in the Process to Routing/Addressing/Worklist Attributes. (Data
for forms should be loaded from a pageflow) On each activity, limit the data in the interface tab to the data used in this activity (for user
tasks, include the data that are used to fill workitem attributes at process level) Set timers on boundaries of activities that are taking time, so that a BPM Thread is not
blocked. start Parallel paths using Timers, is faster (Chaining Usecase) Gateways taking time Parallel Paths are sharing one Engine thread Use Activity level script instead of “Script Tasks”, as they are lighter to run.
(On Activity, script tab: process manager initiate/complete/timeout/cancel scripts) Use Service Process to run several technical activities that do not require auditing Use Pageflows vs. Chaining Use PaaS Interfaces vs. API Use Business Services for Interactive Casestarts fast RQL's should contain only, Business Units, Positions, Groups, UNION, INTERSECT
Set a Common Context Root for your project
You can define a common context root that will be used as a prefix to the URI generated for any system participant. Refer to “Setting a Common Context Root for Web Service Endpoint URIs” in “TIBCO Business Studio™ BPM Implementation”.
Database
For performance database is critical make sure its fast in production/test and that it has low latency connection.
Performance also importance for admin DB. For development I favour using internal DB rather than oracle/sql.
Mediations
When using mediations, try to use them to mediate rather than provide services. Avoid having business logic in mediations.
Example: if a mediation makes 7 calls to AMX:BPM API, with decision points based on input etc its probably not the right place to be doing it! Maybe better to provide services or BPM subprocesses to hold this logic.
Software Management To keep disk space smaller and to keep the Environments clean, older unused Project Templates should be deleted from any installation:
Use AMX Administrator Options, under Infrastructure Software Management:
BPM Enablement CTS Version (TIBCO) 94
TIBCO AMX BPM Best Practices
Delete all unused Features (here marked yellow, with shift+multi select)
Delete all unused Application Templates (here marked yellow, with Strg+multi select, shift is not working here)
Deployment
Make use of CLI deployment scripts to aid deployment and upgrade. When doing development testing (as opposed to proper testing) try to undeploy and redeploy complete package using scripts to avoid confusion/missmatched projects/BOMs etc.
PSG have a pretty good deployment framework for AMX thanks to Richard Armitage it is in use at several customers.
Monitor host stdout during deployment to make sure you aren't tight on memory. You will get memory warnings output to this file.
Never just use force delete after a failed deployment! Instead follow node cleanup process with support.
Make sure free disk space is OK prior to deployment.
Development Environment Rules for follow in best Case 1. Use a VM and snapshot it often 2. Don't run out of disk space under any circumstances 3. Backup before any deployment on prod (maybe on test too if you can't avoid the fixing
time) 4. Make sure you cancel any processes and check for orphaned work items before
BPM Enablement CTS Version (TIBCO) 95
TIBCO AMX BPM Best Practices
undeploying 5. Always untick upgrade box (which removes app first) when deploying unless you really
need to upgrade 6. Don’t do things like undeploy apps that have dependencies on them try and remove
dependencies between apps anyway using dynamic subprocs 7. When you get a problem undeploying or upgrading first step is to restart the node to see if
that fixes it. Then try force undeploy. if that doesn't work you will likely need to do a node cleanup
8. Don't leave features and templates behind make sure you remove them via admin when they aren't used (uninstall form node etc) otherwise you will soon run out of disk space
9. Check node stdout logs for warnings about memory/heap sizes you don't want to run out of memory during deployment
Applicaon Template Cleanup. At deployment me the DAA (design‐me artefact) is converted into a RDA with the actual runme/deployment configuraon added to the app template. RDAs are in the 'runme' directory and are used to run the apps. Therefore any Applicaon Templates can be removed without breaking the running applicaon.
Best pracce is to remove Applicaon Templates once the applicaon is no longer using that version ‐ this implies the applicaon has been either removed or upgraded and no old instances are in use.
Features can not be removed until the application is undeployed or upgraded and the feature is uninstalled from the node. Best practice is to remove features one application is no longer using that version. Features may sometimes need to be removed manually from admin by selecting “uninstall from node”.
Note: features in particular can take excessive disk space so cleanup is mandatory.
