IBM BPM V8.5.5.pdf

Contents Building process applications Business process management and case management Getting started with IBM Process Designer Process Designer interface Where to edit Process Designer artifacts Process Designer tips and shortcuts Concurrent editing Setting preferences Creating new process applications Creating a process application from a WebSphere Business Modeler process Creating processes in IBM Process Designer Modeling processes Creating a business process definition (BPD) Adding lanes to a BPD Adding activities to a BPD Adding events to a BPD Modeling process execution paths by using sequence flows Converging and diverging flows Example gateways Implementing activities in a BPD Implementing a BPD activity as a human service Creating loops for a BPD activity Configuring a BPD activity for simple loops Configuring a BPD activity for multi-instance loops Assigning teams to BPDs and lanes Assigning teams to BPD activities Assigning a dynamically retrieved team Setting up a routing policy (deprecated) Defining rules with a routing policy (deprecated) Assigning an activity to an ad hoc list of users (deprecated) Configuring conditional activities Implementing a conditional activity Managing conditional activities by using the JavaScript API Creating an unstructured (ad hoc) activity Example: Starting an unstructured (ad hoc) activity (JavaScript API) Subprocess types Modeling non-reusable subprocesses Working with linked processes Calling a linked process dynamically Modeling event subprocesses Creating a user attribute definition Validating processes Task types Creating user interfaces for a BPD Building services Service types

1 4 8 9 11 14 16 17 26 28 30 32 34 37 38 39 41 42 45 49 54 55 57 58 61 63 66 67 69 72 73 74 76 77 79 81 85 87 89 91 94 96 97 100 102 104

Service components 108 Building a Decision service 112 Scenario: Creating a Decision service in a Personalized Notification process 115 Adding a Decision service to a process 122 Implementing an activity using a Decision service 124 Attaching a Decision service to a decision gateway 125 Adding a BAL Rule component to a service 128 Creating rules using the rule editor 131 Business rule parts and structure 133 Defining variables in the rule editor 136 Copying and pasting content in the rule editor 138 Setting the rule language 139 Troubleshooting BAL rule editor errors 140 Adding and modifying Decision service variables 142 Default rule variables and parameters 146 Adding variable types and business objects to a Decision service 148 Variable types 150 Testing a Decision service 153 Debugging a Decision service 155 Exception messages in Decision service testing 157 Scenario: Exporting rules to a Rule Execution Server 160 Exporting rules for use in Rule Studio 163 Configuring a remote Decision service 165 Adding a JRules Decision Service component to a service 167 Adding a Decision Table component to a service 170 Authoring rules using JavaScript in a Decision Table component 172 Decision Table controls 174 Specifying variable values using JavaScript 175 BAL reference 176 Decision service limitations 177 Building a client-side human service 178 Building a heritage human service 180 Building an Ajax service 183 Building an integration service 184 Building an advanced integration service 186 Building a General System service 189 Modeling events 190 Event types 191 Modeling delays, escalations, and timeouts by using timer events 195 Modeling message events 198 Using start message events 201 Using intermediate and boundary message events to receive messages 205 Using intermediate message events and message end events to send messages 209 Setting the target for a UCA message event 211 Using message end events 212

Enabling users to perform ad hoc actions (deprecated) 213 Building a sample ad hoc action (deprecated) 214 Testing a sample ad hoc action (deprecated) 216 Modeling event gateways 218 Handling errors using error events 220 Handling errors in BPDs 223 Handling errors in services 225 Error events in models from V7.5.x and earlier 227 Using Service Component Architecture to interact with processes 228 Undercover agents 232 Creating and configuring an undercover agent for a message event 234 Creating and configuring an undercover agent for a scheduled message event 237 Creating and configuring an undercover agent for a content event 240 Documenting development artifacts 242 Linking to external information 243 Process documentation location links 246 Using external implementations 247 Building a custom application to implement an activity 248 Creating an external implementation 249 Using an external implementation to implement an activity 251 Integrating with web services, Java and databases 253 Creating outbound integrations 254 Integrating with web services 256 SOAP headers 258 Creating implicit SOAP headers for outbound web service integrations 260 Adding SOAP headers to a SOAP request message 261 Retrieving SOAP headers from the SOAP response message 263 Adding a web services server 264 Configuring a Web Service Integration component 268 Security for Web Service Integration steps 271 Web service faults 273 Serialization of objects 275 Setting up message-level encryption 276 Troubleshooting web services outbound web service integrations 279 Considerations when using WSDL with multiple XSD or WSDL imports 281 Troubleshooting XML schema messages for web service integrations 282 Calling a Java method in an integration service 287 Sending attachments using an SMTP server 290 Using Business Process Manager SQL Integration services 291 Creating inbound integrations 293 Building a sample inbound integration 294 Adding a message event to a BPD 295 Creating an attached service 296

Creating an undercover agent 297 Attaching the undercover agent to the message event 298 Creating a caller service 300 Creating an inbound web service 301 Testing the integration 304 Creating implicit SOAP headers for inbound web service integrations 306 Retrieving SOAP headers from an inbound request message 307 Adding SOAP headers to an outgoing response message 309 Posting a message to IBM Business Process Manager Event Manager 311 Publishing IBM Business Process Manager web services 315 Web services compatibility 317 Verifying that the web service is working 318 Calling a web service using a SOAP connector 319 Integrating BPDs with IBM Case Manager cases 322 Adding an IBM Case Manager server 323 Building the IBM Case Manager Integration service 325 Building a query for a search case operation 327 Processing a search case operation result 328 Data mapping in case operations 330 Accessing an IBM Case Manager server using the Secure Sockets Layer (SSL) 332 Designing process interactions for business users 333 Configuring a role-based business user interface 334 Exposing business process definitions 335 Exposing the Ad Hoc Reports dashboard 337 Exposing heritage human services 338 Enabling resumable services 343 Globalizing dashboard names 346 Generating portlets for heritage human services exposed as dashboards 347 Exposing client-side human services 352 Making business data available in searches and views 356 Developing flexible and efficient process applications 358 Configuring activities for inline completion 360 Optimizing BPD execution for latency 363 Automatically starting the user's next task 365 Defining ad hoc actions (deprecated) 367 Setting up collaboration features for business users 369 Enabling Sametime Connect integration 370 Specifying experts for an activity 371 Enabling IBM Connections integration 372 Enabling process instance management 374 Setting the work schedule for a BPD 377 Examples 379 Managing time and holiday schedules 380 Specifying activity due dates 381 Generating names for process instances 383

Enabling processes for tracking and reporting Tracking IBM Business Process Manager performance data Data tracking considerations Autotracking performance data KPIs and SLAs Creating custom KPIs Associating KPIs with activities Creating SLAs Setting up autotracking Tracking groups of process variables Creating a tracking group Associating process variables to a tracking group Creating a timing interval Sending tracking definitions to Performance Data Warehouse Exposing performance scoreboards Defining reports (deprecated) Defining a custom layout (deprecated) Building cases Case management overview Case management concepts Scenario: Financial services credit card dispute resolution Scenario: Automobile insurance claims Designing a case Opening Case Designer from Process Center Creating a case type Configuring how a case is started Adding a case type variable or property Adding case type folders Assigning teams to a case type Adding a case activity Setting preconditions Implementing an activity Creating a document type Example document types Creating case user interfaces Testing and debugging a case type Services to support case management applications The IBM BPM content store Case artifacts and the IBM BPM content store Update restrictions for modifying case artifacts Creating a team Using services to define dynamic teams Setting up a team retrieval service Setting up a team filter service Defining team managers Defining Team rules (deprecated) Business objects and variables

384 385 387 389 391 393 394 396 398 399 400 401 402 404 406 407 409 410 413 415 418 420 422 423 425 427 429 431 433 434 437 440 442 444 445 448 450 453 454 456 461 463 465 467 469 470 473

Variable types 475 Variable scope 477 Creating business objects 478 Shared business objects 480 Business objects, attributes, and variables that are renamed 482 Business object advanced properties 485 Declaring and passing variables 491 How variables are passed 493 Declaring variables 496 Mapping input and output data for an activity or step 498 Declaring variables for a subprocess 500 Testing declared variables and data mapping 502 XSD generation pattern for business objects 504 Using JavaScript in BPDs 506 Initializing complex variables 507 Creating exposed process values 508 Adding an EPV to a BPD or service 510 Adding an EPV to a report 511 Setting variables in pre and post assignments 512 Making business data available in searches and views 513 Creating user interfaces for business processes 513 Which artifacts should I use? 515 User interface concepts 517 Human services 519 Dashboards 520 Coaches 521 Coach views 523 Templates 525 Properties 526 General properties 527 Configuration properties and configuration options 529 Positioning options for coach view instances 533 Visibility properties 536 HTML attributes 538 Data binding for coach views 539 Binding data and configuration options 541 Boundary events 547 Event handlers overview 548 Framework managed versus view managed content for coaches 551 Controls 553 Advanced items for coach views 554 Content box 555 Custom HTML 557 Heritage artifacts 559 Difference between heritage human services and client-side human services 561 Difference between coaches and heritage coaches 563

Modeling client-side human services Tools available from the palette for client-side human services Building a client-side human service Implementing a BPD task using a client-side human service Declaring variables JavaScript API for client-side human service authoring Calling another service from a client-side human service Implementing exclusive gateways in client-side human services Saving the state of a client-side human service during execution Validating client-side coaches using client-side validation Validating client-side coaches using server-side validation Handling errors in client-side human services Exposing client-side human services Adding HTML meta tags to client-side human services Enabling work to be postponed and resumed at run time Navigation options for after service completion Running and debugging client-side human services Running client-side human services Debugging client-side human services Troubleshooting errors from running client-side human services Keyboard accessibility for client-side human services Adding nodes to client-side human services by using the keyboard Heritage human service to client-side human service conversion Building coaches Validating coaches in heritage human services Developing reusable coach views Providing information about coach views Defining coach view behavior Improving coach view performance Adding custom AMD modules Accessing a child coach view Configuring the design-time appearance of coach views Adding variables to coach views Defining the contents of coach views Adding bidirectional language support Setting the visibility of coach views Calling Ajax services from coach views Generating URLs of managed assets Generating a unique ID for a coach view Tips for debugging coach view lifecycle method inside client-side human services Tips for debugging coach views in Process Portal Enabling JavaScript debugging for coaches Coach and coach view troubleshooting Responsive settings for coach views Coach and coach view examples Example: creating a template Example: wiring coaches in a human service

565 568 572 574 575 577 582 584 586 588 591 594 596 596 597 599 600 601 602 604 607 610 612 614 617 619 622 624 627 629 631 633 636 637 639 641 646 649 651 652 654 656 657 658 660 661 664

Example: creating a tabbed coach Example: creating a Select control using custom HTML Example: creating a Dojo button control Example: creating a jQuery button control Example: validating a coach in a client-side human service Example: validating a coach in a heritage human service Example: creating a coach that calls an Ajax service Example: creating a coach for tablets and smartphones Example: showing the label of a complex coach view Building Heritage Coaches Adding sections to a Heritage Coach and controlling the layout Setting column widths in a Heritage Coach Setting the number of columns in a Heritage Coach Examples of building services with heritage coaches Example: building an integration service with a Heritage Coach Nesting the Integration service and mapping its variables Building Heritage Coaches to collect input and display output Building a heritage human service with heritage coaches Example: Building a heritage human service with coaches Building an Ajax service with Heritage Coaches Configuring Heritage Coach controls Populating a list with static data Populating a list with dynamic data Binding a complex data structure to a Table control Populating a table control using an SQL query Binding a variable to a custom HTML component Making an input control a required field Displaying a control based on the input value of another control Displaying a control to a specific group Changing the visibility of a Heritage coach control Validating user input Controlling field and other formatting in Heritage Coaches Using pre-defined formats in Heritage Coach Controls Using characters to apply custom numeric formatting Adding custom format types Using formatting with variables Using formatting with language localization resources Configuring a Hebrew or Islamic calendar Aligning buttons in a Heritage Coach Aligning check boxes and radio buttons in a Heritage Coach Adding documents and reports to Heritage Coaches Choosing the type of documents to attach to a Heritage Coach Attaching IBM Business Process Manager documents to a Heritage Coach Attaching ECM documents to a Heritage Coach Embedding documents in a Heritage Coach Embedding IBM Business Process Manager reports in a Heritage Coach Customizing Heritage Coaches

667 673 676 678 680 683 687 690 697 701 702 704 705 706 707 708 709 710 713 715 717 718 719 721 723 725 726 727 729 730 732 733 734 736 740 741 742 743 744 745 746 747 750 753 755 759 760

How Heritage Coaches work Adding custom images to a Heritage Coach Overriding CSS styles for selected controls and fields Specifying a custom CSS for a Heritage Coach Specifying an XSL transform override for a Heritage Coach Setting the length of input text fields Enhancing interface layout using custom attributes System services to implement conditional activities Troubleshooting Heritage Coaches Localizing process applications Creating localization resources Localizing user interfaces Localizing coach view configuration options Versioning process applications Naming conventions Naming conventions for Process Center server deployments Naming conventions for Process Server deployments Enabling document support Working with IBM BPM documents The IBM BPM document store Inbound events for the IBM BPM document store Inbound events for the IBM BPM content store The IBM_BPM_Document document type Creating IBM BPM documents Updating IBM BPM documents Working with the IBM_BPM_Document_Properties property Writing to the IBM_BPM_Document_Properties property Reading from the IBM_BPM_Document_Properties property Updating the IBM_BPM_Document_Properties property Specifying search criteria for the IBM_BPM_Document_Properties property Working with IBM BPM documents in the Document List coach view Limitations in working with IBM BPM documents Integrating with Enterprise Content Management (ECM) systems Adding an Enterprise Content Management server Outbound interactions with Enterprise Content Management systems Authentication scenarios How to use Coach views to store or view documents Configuring coach views for storing and viewing Enterprise Content Management documents Building a service that integrates with an ECM system or the IBM BPM document store Building a query for an Enterprise Content Management search operation Working with a search result programmatically Working with document content Data mapping in Enterprise Content Management operations Inbound events from Enterprise Content Management systems Runtime behavior for inbound content events

761 763 764 766 767 768 769 771 772 773 774 776 777 778 780 782 786 788 789 791 792 794 796 798 799 800 801 802 804 806 807 808 809 810 812 813 815 817 820 824 827 829 831 840 841

Performing modeling tasks for inbound events 842 Subscribing to document and folder events: the end-to-end approach 844 Creating and configuring event subscriptions 848 Content event types 851 Creating attached services 855 Creating and configuring an undercover agent for a content event 856 Adding a content event to a BPD 856 The ECMContentEvent business object 858 Performing administrative tasks for inbound events 859 Creating an event handler for an Enterprise Content Management system 860 Using the event handler for FileNet Content Manager 862 Troubleshooting interactions with Enterprise Content Management systems 867 Integration considerations for ECM products 868 IBM FileNet Content Manager 869 IBM Content Manager 871 Alfresco Community 873 Microsoft SharePoint 875 Accessing the SharePoint CMIS provider from IBM BPM 877 Testing and debugging process applications 880 Visualizing process data 881 Visualize variables 883 Visualize tag groups 884 Keyboard shortcuts for data visualization 885 Running and debugging processes with the Inspector 887 Managing process instances 889 Restricting access to debugging for services 890 Stepping through a process 893 Debugging a process 895 Resolving errors 897 Inspector reference 898 Authentication during playback to handle changes in user identity 903 Globalization 904 Bidirectional support in IBM Business Process Manager 905 Applying bidirectional text layout transformation 906 Contextual support 908 Troubleshooting Process Designer and Process Center connectivity 909 Enabling error logging 911 Troubleshooting Process Designer and Process Center connectivity 913 Enabling error logging 913 SS9KLH_8.5.5/com.ibm.wbpm.ref.doc/topics/rcontext.html 913

Building process applications In IBM® Business Process Manager (BPM), process applications are the containers for business processes and cases that are created in IBM Process Designer. You can either create process applications in Process Center or export and import process applications into Process Center. After a process application is created or imported, it is stored and listed in the Process Center repository. You open process applications in Process Designer where you can create and edit the business process definitions (BPDs) or cases within those process applications. For information about designing high-performing IBM Business Process Manager solutions, see the following publications: - For designing processes, see Chapter 5: Design considerations and patterns in Business Process Management Design Guide: Using IBM Business Process Manager. - For best practices, see Chapter 2: Architecture best practices and Chapter 3: Development best practices in IBM Business Process Manager V8.5 Performance Tuning and Best Practices. - For an overview of critical performance-related information, see IBM Business Process Manager V8.5 Performance Tuning. The following high-level diagram illustrates the basic tasks and activities that are typically associated with building a process application.

- Business process management and case management Business process management and case management are two approaches to build a process. The type of business situation you are addressing determines which approach you use.Case management functions are only available if you have IBM BPM Advanced with the Basic Case Management feature installed.

1

- Getting started with IBM Process Designer Process Designer is an easy-to-use graphics-oriented tool that enables you to model and implement your business processes and easily demonstrate process design and functionality during development efforts. This overview describes how to begin using all of the tools that are available with Process Designer. - Creating new process applications When you create a new process application, you provide a name, acronym, and optional description of the process application. - Creating a process application from a WebSphere Business Modeler process You can import business processes from WebSphere Business Modeler to Process Designer. - Creating processes in IBM Process Designer Create processes in Process Designer that represent the processes in your company. When you run your processes inside Process Designer, you can analyze and simulate them in order to optimize your business activity. Building cases A case is a project that starts and finishes over time to resolve a problem. The problem can involve a claim or a request or a proposal and be supplemented by many documents and records relevant to the case. A case usually involves multiple people from inside and outside of an organization. These people often have a relationship to each other. For example, a customer with a problem and a corporate support representative who solves the problem for the customer. - Creating a team A team is a group of users that perform similar tasks, and consists of a set of members and a team of managers. Teams are used to manage the tasks that users can perform in Process Portal. Because any team can be added as the manager of another team, you can flexibly define your organization's management structure. - Business objects and variables In Process Designer, variables capture the business data that is used by activities in a business process definition or by steps in services such as integration services or human services. - Creating user interfaces for business processes In IBM Business Process Manager, human services provide the logic and user interface through which users can view and interact with business processes, cases, data or process instances. - Versioning process applications Versioning provides the ability for the runtime environment to identify snapshots in the lifecycle of a process application, and to be able to concurrently run multiple snapshots on a process server. - Enabling document support - Testing and debugging process applications - Globalization To ensure that applications can be used in multiple geographical locations and cultures, globalization support is built in through appropriate design and implementation of systems, software, and procedures. IBM Business Process Manager provides globalization support for single- and multi-byte character sets and for bidirectional transformation including contextual support, support for text 2

layout transformation, and calendar support for Hebrew and Hijri. - Troubleshooting Process Designer and Process Center connectivity Resolve problems starting Process Designer, for example during login, by using various techniques such as correcting invalid connection information or logging errors that are captured with log4J or java.util.logging.

3

Business process management and case management Business process management and case management are two approaches to build a process. The type of business situation you are addressing determines which approach you use.Case management functions are only available if you have IBM BPM Advanced with the Basic Case Management feature installed. IBM® Business Process Manager provides tools for the approaches to define and then improve a process: business process management and case management. Learn the differences so that you can select the best approach for your situation. Consider two types of situations that a corporation faces. In the first situation, the corporation wants more customers to use its credit card. In the second situation, the corporation wants a process to handle calls about credit card billing problems. The following sections describe the design and implementation you would likely use for each situation. - Designs for two types of business situations - Building and running a business process - Building and running a case - Key differences between business process management and case management

Designs for two types of business situations If you needed to get more customers to use your credit card, you might come up with the following activities: 1. Define the type of customer you think might benefit from your credit card. 2. Use an application to search a database for potential candidates. 3. Use an application to email the candidates. 4. Review the candidates who responded to assess the effectiveness of the email and determine patterns in the list of interested customers. 5. Use an application to check the credit rating of the respondents. 6. Use an application to mail the credit cards to candidates with good credit ratings. The activities are in order and their order follows a predictable and repeatable process. The process determines the sequence of events. It is a stable process that likely remains unchanged over many years. A number of the actions can be automated. In this scenario, a business process would most likely be your implementation choice. If you wanted to handle customers with credit card billing problems, you might come up with the following unordered activities: - Capture the complaint when someone called or sent an email. - Get information about the customer. - Get information about the vendor. - Collect receipts and invoices to verify the complaint. - Notify Customer Records if unusual information was found. - Notify system administrators if the billing system caused problems. - Notify Vendor Records if unusual information was found. - Resolve the dispute.

4

The activities are unordered because the sequence of activities is unpredictable. The events determine the order in which the activities in the process are followed. People rather than programs interact to resolve the dispute. External documents are needed for verification. In this scenario, a case would most likely be your implementation choice.

Example of building and running a business process The following business process might get more customers to use the corporation's credit card. It is a wired process. You can see which activity follows the other. At run time, the activities drive the events. For example, a worker defines the type of customer that the worker is looking for and then starts the application to get the candidates and email the candidates. Then, the worker waits until there is a list of candidates to review based on the people who responded to the email. Finally, the worker starts the credit check application. The credit check application is followed by the application that mails out the credit cards. A worker at run time does not select the next activity from a set of choices to choose what comes next; the next activity is predetermined at development time. The activities are in swimlanes that define the type of activity. The team lane is for activities that people do and the system lane is for activities that programs do. Programs automate and complete many activities. To implement these activities with human services, subprocesses, services, and teams, you use the same set of tools as you do to implement a case.

Example of building and running a case The following case might handle credit card billing complaints. The activities are not wired. No predetermined sequence is set at development time. A worker would likely start by describing the complaint and finish by resolving the dispute. However, whether the worker receives the customer information before the vendor information would likely be determined by what the worker read in the complaint. The information that is retrieved about the customer would determine whether the worker would check with the people who handle the customer records. The information that is retrieved about the vendor would determine whether the worker would check with the people who handle vendor records. The information that is retrieved about either the customer or the vendor might lead to investigating the computer billing system for problems. The activities are not in a swimlane that determines their type. Although the worker 5

controls the process at run time, the process is dynamic and influenced by current events. As in a business process, the required activities must be completed. However, optional activities do not need to be completed. People who interact with other people, rather than automated programs, determine the activities. To verify the complaint, receipts and invoices, which are external documents independent of the case, must be captured. To implement these activities with human services, subprocesses, services, and teams, you use the same set of tools as you do to implement a business process.

Key differences between business process management and case management Considering the previous scenarios, the following table summarizes the characteristics of business process management and case management. Examining these characteristics, you can select which type of process might best suit your situation. Table 1. Characteristics of business process management and case management Business process management You can define an ordered sequence of activities that can be completed to solve a business challenge. The sequence of activities is stable and seldom changes; that is, the process is predicable and repeatable. The process determines the events. The first activity determines the first set of events, which then leads to the next activity and the next set of events. The activities are wired to one another, which determines the sequence.

Case management You can define an unordered set of activities that can be completed to solve a business challenge. The activities occur in an unpredictable order. The events determine the process. As events occur, a worker selects the appropriate activity. The resulting process can vary depending on the current event and the subsequent selection by the worker. Activities are not wired to one another.

6

The activities are often programmatic. A repeatable sequence, such as selecting a set of potential credit card owners from a database, can be automated. External documents are not part of the process.

People primarily determine the activities. Handling a customer with a billing error is done by a person who uses judgment to determine the best resolution of this particular case. External documents play a key role. For example, receipts provide a record for how the problem that must be resolved began.

Parent topic:Building process applications

7

Getting started with IBM Process Designer Process Designer is an easy-to-use graphics-oriented tool that enables you to model and implement your business processes and easily demonstrate process design and functionality during development efforts. This overview describes how to begin using all of the tools that are available with Process Designer. For a high-level overview of the components of the Process Designer interface, watch Getting Started with Process Designer version 8.5.5, available on YouTube or in the IBM Education Assistant information center. A transcript of the video is available. - Process Designer interface Before you start to build processes with IBM Process Designer, you must understand the tools that are available in the Process Designer interface. - Where to edit Process Designer artifacts Learn where you can edit artifacts in IBM Process Designer. - Process Designer tips and shortcuts You can use several features in Process Designer to improve your efficiency. - Concurrent editing Multiple users can simultaneously access and change process applications and library items in IBM Process Designer. When you edit concurrently, you collaborate with other team members to create the library items that you need for your project. For example, you can communicate about your ideas and edits with instant messaging and see the results in the Designer view as they happen. - Setting preferences IBM Process Designer provides several settings to control the appearance and functionality of the editors and interfaces that it includes. Parent topic:Building process applications

8

Process Designer interface Before you start to build processes with IBM® Process Designer, you must understand the tools that are available in the Process Designer interface. The Process Designer interface provides the tools to model your processes in IBM BPM. The following image and corresponding table describe the parts of the Designer view that you interact with when modeling processes and implementing the steps in those processes.

Table 1. Description of numbered areas on the Designer interface image Number 1

Area Main toolbar

2

Library

Description Provides access to the Designer view and Inspector. Also provides access to Process Center and Optimizer if you open the Process Designer desktop editor. The main toolbar is also where you go to save all open editors, take a snapshot, and view web-based help. Provides access to the library items for the current process application. You can create and edit library items, as described in Managing library items in the Designer view. Note: Users who have administrative access to the application control access to process applications. For more information, see Managing access to the Process Center repository.

9

3

Main canvas

4

Palette

5

Property manager

Parent topic:Getting started with IBM Process Designer Related information: Known issues for translated IBM BPM components

10

Where you can graphically model and configure your process and design the layout of coaches, human services, and heritage human services. Provides BPMN elements and variables that you can use to model and configure your process. Where you can set properties and configuration options for selected components in your process.

Where to edit Process Designer artifacts Learn where you can edit artifacts in IBM® Process Designer. In previous releases, you worked with artifacts in Process Designer on your desktop. Now, you can work with artifacts that are in the Process Designer web editor and in the Process Designer desktop editor. For example, to create process applications that contain business process definitions (BPDs) and client-side human services, you must use both the desktop editor and the web editor because there are some Process Designer capabilities that you can access only on the web and some that you can access only on your desktop. Multiple users can work simultaneously on the same process applications and artifacts in the two editors and changes happen automatically and seamlessly. If you have Process Designer open on your desktop and you are working in the web editor, you can edit certain artifacts in the desktop editor. When you click the artifacts in the web editor, they open in the desktop editor so that you can edit them. You can access the Process Designer web editor in the following ways: - Open Process Designer desktop editor and then select an artifact that is editable only on the web, such as a client-side human service, case type, or document type. Case management functions are only available if you have IBM BPM Advanced with the Basic Case Management feature installed. - Open Process Designer desktop editor, select a coach view, and then right-click and select Open in > Web Editor. The following table lists which artifacts you can edit where (indicated with asterisks). You can edit some artifacts in the desktop editor. You can edit other artifacts in the web editor. The web editor opens in a web browser from Process Designer. Table 1. Where you can edit Process Designer artifacts Artifacts

Editable in the Process Designer desktop editor *

Advanced Integration service Ajax service * business object * BPD * case typeNote:Case management functions are only available if you have IBM BPM Advanced with the Basic Case Management feature installed.

Editable in the Process Designer web editor

* *

11

coach viewNote: To use responsive features in coach views, for example to have the runtime behavior respond to different screen size environments, you must edit coach views in the web editor. client-side human service decision service design file document typeNote:Case management functions are only available if you have IBM BPM Advanced with the Basic Case Management feature installed. event subscription external implementation exposed process value General System service heritage human service historical analysis scenario IBM Case Manager Integration service Integration service key performance indicator (KPI) localization resource process application setting server file service-level agreement simulation analysis scenario teamNote: To define a team using a filter or retrieval service, you need to edit this artifact in the Process Designer desktop editor. timing interval tracking group undercover agent user attribute definition web file

*

*

* * * *

* * * * * * * * * * * * * *

*

*

*

* * * * *

*

*

12

web service

*

Parent topic:Getting started with IBM Process Designer

13

Process Designer

tips and shortcuts

You can use several features in Process Designer to improve your efficiency. When you start using the Designer interface in Process Designer, there are some tips and shortcuts to keep in mind. The following are tips and shortcuts for the Process Designer desktop editor: - To maximize the space available for the main canvas, you can hide the library by clicking the toggle at the bottom of the Revision History. You can also hide the palette by clicking the left margin of the palette. Click the toggle icon and the palette margin to restore the library and the palette. - To move from one open library item to another, click the arrow keys or the menu at the top of the window. - Unsaved changes have an asterisk next to the item name at the top of the window. - To create a new library item while you are working in the Designer view, press Ctrl+Shift+N. - To open an existing library item while you are working in the Designer view, press Ctrl+Shift+O. - To choose multiple items in a category, press and hold the Ctrl key and then click each item. - You can capture your development progress in snapshots as described in Creating snapshots in the Designer view. - You can revert to a previous snapshot (version) of a library item as described in Reverting to a previous version of a library item. - You can copy the previous snapshot (version) of a library item to your current project as described in Copying an asset from a snapshot. - You can add a dependency to a toolkit to use the library items from that toolkit as described in Creating, changing, and deleting a toolkit dependency in the Designer view. - You can see updates that are made by other users as described in Concurrent editing. - For quick and easy access of particular library items, you can create favorites as described in Creating favorites. - To group library items for easy access, follow the instructions in Tagging library items. - To create smart folders of library items, follow the instructions in Organizing library items in smart folders. - To move or copy library items from one process application to another, follow the instructions in Copying or moving library items. - To add and manage external files as part of your IBM® BPM project, see Managing external files. The following are tips and shortcuts for the Process Designer web editor: - Click the "Hide the Library" icon at the top left corner of Process Designer to hide the library. - To maximize the space available for in the main canvas, you can resize the palette and the main canvas and you can also hide the property manager by clicking the arrow below the main canvas.

14

- To move from one open library item to another, click the arrow keys or the menu at the top of the window. - To choose multiple items in a category, press and hold the Ctrl key and then click each item. - You can capture your development progress in snapshots as described in Creating snapshots in the Designer view. - Unsaved changes have an asterisk next to the item name at the top of the window. - You can add a dependency to a toolkit to use the library items from that toolkit as described in Creating, changing, and deleting a toolkit dependency in the Designer view. - You can see updates that are made by other users as described in Concurrent editing. - To tag library items for easy access, follow the instructions in Tagging library items. - To move or copy library items from one process application to another, follow the instructions in Copying or moving library items. - To add and manage external files as part of your IBM BPM project, see Managing external files. Parent topic:Getting started with IBM Process Designer

15

Concurrent editing Multiple users can simultaneously access and change process applications and library items in IBM® Process Designer. When you edit concurrently, you collaborate with other team members to create the library items that you need for your project. For example, you can communicate about your ideas and edits with instant messaging and see the results in the Designer view as they happen. Note: Each user must be connected to the same Process Center and each user must have write access to the process application or toolkit where the library items are located. When you edit concurrently with other users, ensure that your connection status is good. When you are working in the Designer view, you can see when other users are working in the same process application, as shown in the following screen capture:

You can also see when others are viewing or editing the same library item, as shown in the following screen capture:

When multiple users work on the same library item, such as a human service, each user can see the changes when edits are saved. To ensure that all users are aware which library items are open and what changes are being made, Process Designer provides the following notifications: - When another user opens a library item by showing a user icon. You can hover over the icon to see who that user is. - When another user is editing a library item by displaying the words Read Only next to the library item. When a user saves their work, the library item will be available to edit. - When another user has saved changes while you are editing a library item by displaying the words Read Only next to the library item. When you click Save, a Save conflict message displays to ask you either to save your changes and override the other user's changes or discard the changes and accept the other user's changes. - When multiple users start to edit a library item at the same time, before the Read Only text appears, by displaying a warning icon and message to suggest to each user that they either immediately save their changes or discard them. Parent topic:Getting started with IBM Process Designer

16

Setting preferences IBM® Process Designer provides several settings to control the appearance and functionality of the editors and interfaces that it includes.

Process Designer preferences The following steps describe how to access the preference settings and the following table describes the options that are available: 1. Select File > Preferences from the main menu. 2. Click the IBM BPM entry to display the available options. 3. Click the option that you want. For example, to set the user name for Blueworks Live™ process subscriptions, click the Blueworks Live option. Table 1. Options for IBM Process Designer preferences Option Blueworks Live

Capabilities

Decisions JavaScript

Optimizer Settings

Description Set the Blueworks Live server URL and email address for Blueworks Live process subscriptions.Tip: Changing the email address or the URL logs you out of Blueworks Live. Control the capabilities of the current user. For example, to create external activities in IBM Process Designer, you must enable IBM BPM Developer Capability and IBM BPM Advanced Features. Control the locale setting for BAL Rules. Set preferences for the JavaScript editor included in IBM Process Designer. For example, you can choose whether to display JavaScript warnings. Set options for the Optimizer. For example, the KPI thresholds that are used by the Visualization Modes are the thresholds from the current working version of your process application or toolkit. If you want to use the KPI thresholds from the snapshot (version) of your process application or toolkit that was most recently run and tracked, change the Optimizer to the following preference setting: Use the KPI threshold values from the actual version of the Process App/Toolkit.

17

Passwords Web Browser

Manage the passwords that are stored when running tasks from the Inspector. Select the web browser to use when web pages are opened from IBM Process Designer. If you do not see a particular external web browser as an option, click New to add it.

Process Center Console preferences To set the locale for IBM Process Center Console and Process Designer, access the Process Center Console by opening your web browser to the following location: http://[host_name]:[port]/ProcessCenter. Click Preferences in the upper right corner and choose the language that you want from the list. When you change the locale, you must exit and then restart IBM Process Designer for the change to take effect. (When you are accessing Process Center Console from a browser, you can log out and then log back in for the change to take effect.) The locale preference that you selected applies to the user who logs in. Each IBM Business Process Manager interface that is started by the same user in the same environment uses this preference setting.

Process Designer XML configuration settings The IBM BPM settings related to Process Designer are transferred through the network from Process Center to Process Designer as properties of the AuthoringEnvironmentConfig configuration object every time Process Designer is launched. These properties affect the connections created between Process Designer and Process Center. Based on your business requirements, you might want to change the properties of Process Designer. For IBM BPM XML configuration settings that are related to Process Designer, see the following table that contains properties and explains how to set the properties. The AuthoringEnvironmentConfig object contains the following properties: Name Images Prefix

Description The Images Prefix endpoint maps to the AE_IMAGES_PREFIX scenario key, which configures the URLs that are used in the Process Designer authoring environment to get images.

18

Additional Information Information about using the scenario keys to configure the IBM BPM endpoints is described in the topic Configuring endpoints to match your topology.

Portal Prefix

The Portal Prefix endpoint maps to the AE_PORTAL_PREFIX scenario key, which configures the URLs that are used in the Process Designer authoring environment to reach Process Portal. Repository Prefix The Repository Prefix endpoint maps to the AE_REPOSITORY_PREFI X scenario key, which configures the URLs that are used in the Process Designer authoring environment to reach the repository. Servlet Prefix The Servlet Prefix endpoint maps to the AE_SERVLET_PREFIX scenario key, which configures the URLs that are used in the Process Designer. This scenario must specify an absolute URL by setting the url property. Social Bus WebApp Prefix The Social Bus WebApp Prefix endpoint maps to the AE_SOCIALBUS_WEBAP P_PREFIX scenario key, which configures the URLs that are used in the Process Designer authoring environment to reach the social bus web application. Web API Prefix The Web API Prefix endpoint maps to the AE_WEBAPI_PREFIX scenario key, which configures the URLs that are used in the Process Designer authoring environment to reach the web API.

19

REST Gateway Prefix

The REST Gateway Prefix endpoint maps to the AE_REST_GATEWAY_CR _PREFIX scenario key, which configures the URL that is used in the Process Designer authoring environment to reach the Process Center REST Gateway. Web PD Prefix The Web PD Prefix endpoint maps to the AE_WEB_PD_PREFIX scenario key, which configures the URL that is used in the Process Designer authoring environment to launch the web editor. Webviewer WebApp Prefix The Webviewer WebApp Prefix specifies the endpoint of the web application contained in the webviewer.war file.The host and port number of the URL can be customized by setting the IBM BPM virtual host. The context root of the URL can be customized by adding a prefix before the context root. BPM Asset Prefix The BPM Asset Prefix specifies the endpoint of the web application contained in the bpmasset.war file. The host and port number of the URL can be customized by setting the IBM BPM virtual host. The context root of the URL can be customized by adding a prefix before the context root.

20

Information on setting the IBM BPM virtual host is found in the topic Configuring endpoints to match your topology. For information about setting the context root prefix, see the topic BPMConfig command-line utility.

Process Portal Prefix

HTTP Protocol Only

The Process Portal Prefix specifies the endpoint of the web application contained in the processportal.war file. The host and port number of the URL can be customized by setting the IBM BPM virtual host. The context root of the URL can be customized by adding a prefix before the context root. For example, /prefix/ProcessPortal. If this attribute is set (which is the default), communication between Process Designer and Process Center is limited to using HTTP or HTTPS protocols instead of RMI with JMS. Note that if the attribute is not set, HTTP or HTTPS communication still occurs between some Process Designer components and Process Center, but not exclusively.

21

Information on setting the httpProtocolOnly

attribute is found in the topic Configuring the httpProtocolOnly property for Process Designer.

Suppress Redirect URL Password

Specifies whether to suppress the inclusion of the user password in the URLs that Process Designer opens. For example, each time you run a playback in Process Designer, a new Process Portal browser session is opened. Process Designer then submits the user credentials, which consist of the user ID and password, and the browser session uses these credentials to log in. The

Information on setting the suppressRedirectUrlPas swd attribute is found in the

topic Installing IBM Process Designer.

suppressRedirectUrlPas swd option stops the

password from being included in the URL to improve security. Note: When you use the suppressRedirectUrlPas swd option, you only need

Formatting Templates

to log into the browser the first time that you open a web editable artifact or run a playback in Process Designer. This option only applies to Process Designer and can be turned on and off as needed. Specifies the predefined character formats for text controls or specifies the creation of additional formats. The data type is FormattingTemplatesConfi g.

22

These properties are all configured using IBM BPM configuration XML files. For information about setting the properties, see the topic Changing IBM Process Server properties in 100Custom.xml.

Inspector

This property specifies inspector configuration. The data type is InspectorConfig. role1 role2

Library Event Stream Manager

The data type is SequencedStateDeltaMan agerConfig. 15 15 15 15 15

Mime Types

The data type is MimeTypesConfig.

Repository Broken Ping Time

Specify an integer value. The default value is 15000 if the value is set to 0 or a value is not specified.

Repository Max Wait During Shutdown

Specify an integer value. The default value is 3000 if the value is set to 0 or a value is not specified.

23

Repository Ping Delay

Specify an integer value. The default value is 15000 if the value is set to 0 or a value is not specified.

Repository Slow Ping Time Specify an integer value. The default value is 7500 if the value is set to 0 or a value is not specified.

Add Redirect URL Credentials

Specifies whether the credentials are permitted to be passed in IBM Business Process Manager URLs. For example, a service can be started directly from IBM Process Designer without presenting a login screen. The default value is true. true

Deploy Snapshot Using HTTPS

Specifies whether the Process Center Server uses HTTPS to deploy process applications and toolkits to process servers. If the property is set to the default value of true and all process servers are secure, then communication from Process Center to Process Server will work with HTTP Secure (HTTPS) or HTTP over SSL. However, if you have a mix of secure and non-secure servers, Process Center can only communicate with Process Servers that are configured to work with this mixed configuration. true

24

Encode Redirect URL Credentials

Specifies whether the credentials that are passed in an IBM Business Process Manager URL that implements redirectlogin.jsp are encoded. For example, you can encode credentials in a URL that is used to start a service directly from IBM Process Designer. By default, this property is set to true, which specifies that the credentials passed in an IBM BPM URL are encoded. If you change the setting to false, the URL is composed with credentials in plain text. true

Parent topic:Getting started with IBM Process Designer

25

Creating new process applications When you create a new process application, you provide a name, acronym, and optional description of the process application.

About this task You create new process applications in Process Center. You can access the Process Center console in the following ways: - From entering the remote Process Center URL (for example https://servername:9080/ProcessCenter/login) into a web browser. - By starting the Process Designer desktop editor. Tip: If you are creating processes in your process application, use the Process Designer desktop editor. If you are building cases in your process application, use the remote Process Center URL.

Procedure To create a new process application, complete the following steps: 1. Start the Process Designer desktop editor or enter the remote Process Center URL into a web browser. 2. In the Process Apps tab, click the Create New Process App option. 3. In the Create New Process App window, enter a name, acronym, and description of the process application. Ensure that the acronym for the process application is unique and limited to seven characters. IBM® Business Process Manager (BPM) uses the acronym as an identifier for this process application and the library items that it contains. For example, when you manipulate the items in the process application with the IBM BPM JavaScript API, you can use the acronym to specify the namespace of the items. For example, when you manipulate the items in the process application with the IBM BPM JavaScript API, you can use the acronym to specify the namespace of the items. The acronym for the process application must be unique and limited to 7 characters. IBM BPM uses the acronym as an identifier for this process application and the library items that it contains. For example, when you manipulate the items within the process application with the IBM BPM JavaScript API, you can use the acronym to specify the namespace of the items. Providing a description is optional. When you enter a description, you can view it in the Process Center console by clicking the question mark next to the process application name. 4. If you are building cases in the process application, you can select Allow users to open the process application in the web-based Case Designer. For more information, see Opening Case Designer from Process Center.Note:Case management functions are only available if you have IBM BPM Advanced with the Basic Case Management feature installed. 5. To create library items in the process application, click the appropriate option: - Open in Designer Open in Case DesignerNote:Case management functions are only available if you have IBM BPM Advanced with the Basic Case

26

Management feature installed. You see the Open in Case Designer option only if you selected the option described in step 4.

What to do next - To use tracks in this process application, enable the tracks in the Process Center console. - You can create toolkits to enable Process Designer users to share library items across process applications.

Parent topic:Building process applications

27

Creating a process application from a WebSphere Business Modeler process You can import business processes from WebSphere Business Modeler to Process Designer.

About this task You can do this by importing the BPMN models that you exported earlier from WebSphere Business Modeler BPMN 2.0 file archive (.zip) files. You can import your models into the IBM Process Center. You can then use the IBM Process Designer to open the resulting Process App or Toolkit, if you want to see the details of what was imported or to make changes to the imported models.

Procedure To import BPMN models into the IBM® Process Center complete the following steps: 1. Start the IBM Process Designer from your Windows desktop or using the URL for the Process Center in a browser. The first time you start the IBM Process Designer it opens to the Process Center console.You can trigger the import of the models in two ways. You can either click Import Process App (on the Process App tab), or Import Toolkit (on the Toolkit tab). Either of these actions will result in an import window. 2. Click Import Process App. The Import Process App window displays. 3. Click Browse to select the BPMN 2.0 archive (.zip) file that you exported from IBM WebSphere® Business Modeler and click Next. 4. In the Import Process App window, a name and acronym have been specified based on information in the file you selected. You can edit the name and acronym and add a description. If you are using IBM BPM Advanced, you will see radio buttons that you can use to choose what will be generated for unimplemented services. Select either Advanced Integration Services or Integration Services and then click Next. Note: Advanced integration services are only available for unimplemented services. Integration services are always generated for implemented services. Both radio buttons display only in IBM BPM Advanced. For more information, see Building an Integration service and Building an Advanced Integration service. A Summary of the import results pane opens containing any generated error, warning and information messages. A new process application or a toolkit is created, containing the content from the BPMN 2.0 archive. It will include integration services if the model contained web service bindings and advanced integration services if the model contained unimplemented advanced integration services. All Blueworks Live artifacts will also be integrated with a BPMN import if Blueworks Live phases and other BPMN 2 extensions were in the model. A snapshot of the process application is automatically created in the Process Center, for your use as a baseline, in the future, if necessary.

28

5. You can filter the messages by clicking Errors or Warnings. Click Save and specify a location if you want to save the messages. All the messages will be saved as a text file even if a filter has been applied. Click Close.

What to do next You have now imported your BPMN models successfully into the Process Center. The following procedure helps you identify the step-by-step actions you will take after a successful import. However these steps will vary depending on the contents of your model and how you intend to make use of these models in the future. If you had seen warning messages at the end of your import it is likely that you may need to take some remedial action. Warnings usually indicate an unsupported construct or invalid input model. For each warning, examine the contents of what was generated and take additional action as required. Parent topic:Building process applications

Next Steps after importing BPMN Models Procedure 1. Open the Process App or Toolkit that you created 2. Open every single generated artifact and ensure that its contents appear as expected. 3. Replace any of the default generated logic with the intended logic wherever necessary. 4. Complete the following steps for each of the following artifact:Services: Enter the service flow details A. Human services: Customize the default generated coach B. Rule services: Enter the rule details Teams: Specify the team members Processes: A. Private Variables: Provide default values for any variables that are not initialized. B. XOR and IOR Gateways: Enter the conditional logic C. Javascript Activities: Enter the javascript logic D. Adjust the process layout to minimize connection crossing. 5. Check for validation messages and fix them as necessary.

29

Creating processes in IBM Process Designer Create processes in Process Designer that represent the processes in your company. When you run your processes inside Process Designer, you can analyze and simulate them in order to optimize your business activity. The following diagram illustrates the main tasks and activities that are associated with creating processes.

- Modeling processes A process is the major unit of logic in IBM Business Process Manager (BPM). It is the container for all components of a business process definition (BPD). Modeling a good process that matches your requirements is at the core of Process Designer. - Designing process interactions for business users After you deploy a business process definition that you have built in Process Designer to the Process Portal, a business user might interact with it in a number of ways. The user might be the one to launch the process, or the user might be assigned individual activities in the process. - Enabling processes for tracking and reporting IBM Business Process Manager provides ways to collect and consume process performance information. To take advantage of this information, you enable to design your processes to make them trackable. Parent topic:Building process applications

30

31

Modeling processes A process is the major unit of logic in IBM® Business Process Manager (BPM). It is the container for all components of a business process definition (BPD). Modeling a good process that matches your requirements is at the core of Process Designer. Many different individuals from various organizations are involved in developing processes with IBM BPM. The overriding concern is to ensure that you are building the best possible solution for meeting the stated goals of your project. To ensure successful results, team members must work together to capture process requirements and iteratively develop the model and its implementations, as specified in the IBM Business Process Manager overview. - Creating a business process definition (BPD) To model a process, you must create a business process definition (BPD). A BPD is a reusable model of a process that defines the common aspects of all runtime instances of that process model. - Building services Use services to implement the activities in a business process definition (BPD). When a BPD starts and the tasks within it are invoked, services perform the required functions. - Modeling events Events in IBM Business Process Manager can be triggered by a due date passing, an exception, or a incoming message from an external system. You can add events to your BPDs that can occur at the beginning, during, or at the end of a process. Use events to track data, manage errors, and retrieve information about the execution of your BPDs. - Documenting development artifacts As you develop your process application, you might want to capture information about the artifacts that you are creating. Each artifact in IBM Process Designer has a documentation field for this purpose. You can enter text or links to external resources such as web sites or attachments. - Using external implementations You can create external implementations for activities that are handled by applications outside of IBM Business Process Manager. For example, you can model an activity that is run by a custom Eclipse RCP or Microsoft .NET application. - Integrating with web services, Java and databases You can configure IBM BPM processes to communicate with an external system to retrieve, update, or insert data. And, external applications can call into IBM BPM to initiate services. You can manage inbound and outbound communication with external systems using undercover agents, web services, and integration services. - Integrating BPDs with IBM Case Manager cases To integrate with IBM Case Manager, you build an integration service and perform other key steps when you want to integrate a business process developed in IBM Process Designer with a case management case in IBM Case Manager. Parent topic:Creating processes in IBM Process Designer

32

33

Creating a business process definition (BPD) To model a process, you must create a business process definition (BPD). A BPD is a reusable model of a process that defines the common aspects of all runtime instances of that process model.

Before you begin To perform this task, you must be in the IBM® Process Designer desktop editor. Ensure that you have access to a process application in the Process Center repository.

About this task Process modeling captures the ordered sequence of activities within a process along with supporting information from end to end. In process modeling, the business process is framed in a BPD to reflect the activities, the roles that conduct those activities, conditional branching, and the sequence of the workflow between the activities.Tip: When you create a BPD, use the Business Process Model and Notation (BPMN) standards so that everyone who is involved with the process can interpret and understand the process model. BPMN also compacts your BPD by using symbols to represent ideas. Tip: Create BPDs in a process application, not in a toolkit. A BPD in a toolkit can result in process instances running inside the toolkit. A process instance running in a toolkit cannot be migrated. A business process definition needs to include a lane for each system or group of users who participates in a process. A lane can be a participant lane or a system lane. However, you can create a BPD that groups the activities of a group and a system into a single lane if that is your preference. You can designate any specific person or group to be responsible for the activities in a participant lane. Each lane that you create is assigned to the All Users group by default. You can use this default group for running and testing your BPD in the Inspector. The All Users group includes all users who are members of the tw_allusers security group, which is a special security group that automatically includes all users in the system. A system lane contains activities handled by a specific IBM Process Center system. Each activity needs an implementation, which defines the activity and sets the properties for the task. During implementation, a developer creates a service or writes the JavaScript necessary to complete the activities in a system lane. For each BPD that you create, you need to declare variables to capture the business data that is passed from activity to activity in your process. You can also add events to a BPD. Events in IBM BPM can be triggered by a due date passing, an exception, or a message arriving. The trigger that you want determines the type of event you choose to implement.

Procedure

34

1. Open the Process Designer desktop editor. 2. Open a process application in the Designer view. 3. Click the plus sign next to Processes and select Business Process Definition from the list and complete the fields in the New Business Process Definition window. 4. Design your process by dragging BPMN elements from the palette onto the diagram area. 5. To specify the details for an element, select the element in the diagram and edit its properties in the Properties view. - Adding lanes to a BPD A Business Process Definition (BPD) can include a lane for each system or team of users who participate in a process. A lane is the container for all the activities to be carried out by a specific team or by a system. - Adding activities to a BPD In a business process definition (BPD), you can include activities that represent logical work that a specific team or a system completes. - Adding events to a BPD When modeling a process, you might want to model events that can occur at the beginning, during, or at the end of a runtime process (as opposed to activities that are carried out by participants in the process). - Modeling process execution paths by using sequence flows Use sequence flows to connect activities and other modeling constructs to establish the process flow. - Converging and diverging flows Gateways control the divergence and convergence of a sequence flow, determining branching and merging of the paths that a runtime process or case instance can take. - Example gateways The following samples illustrate how to model several types of gateways. - Implementing activities in a BPD Choose the implementation for each activity in your BPD and set the required properties. - Assigning teams to BPDs and lanes Assign teams of users that can start activities, and teams that can work on activities in Process Portal. You can assign a team of instance owners for a BPD, or you can assign teams for individual activities and lanes. - Assigning teams to BPD activities For any activity with a service implementation, you can designate the users who receive the runtime task by using the Assignments page in the properties for that activity. - Configuring conditional activities You can use conditional activities to model steps which are either skipped or completed during run time based on the values of specific process variables. The decision to skip or complete a conditional activity can be made by the runtime user or programmatically, based on scripted rules. - Creating an unstructured (ad hoc) activity An ad hoc activity has no input wires and is started as required by knowledge 35

workers or according to predefined preconditions, rather than by a predefined process flow. Such activities can be required or optional, and they can be defined as repeatable or to run at most once. Knowledge workers can start unstructured activities from the Activities section in the Process Instance details page in Process Portal. - Subprocess types Subprocess is an option for encapsulating logically related steps within a parent process. Steps in a subprocess can directly access business objects (variables) from the parent process. No data mapping is required. However, unlike a linked process, a subprocess can be accessed and instantiated only from the parent BPD, and it is not reusable by any other process or subprocess. - Creating a user attribute definition You can associate unique capabilities or qualities with one or more users by creating user attribute definitions. - Validating processes Use validation functions to refine process definitions as you build them. - Task types Learn more about the task types that are available when modeling with IBM Process Designer. - Creating user interfaces for a BPD Create customized user interfaces that a user sees for the process instance in Process Portal. Parent topic:Modeling processes Related information: Business process definitions (BPDs) Modeling events Declaring and passing variables Service types

36

Adding lanes to a BPD A Business Process Definition (BPD) can include a lane for each system or team of users who participate in a process. A lane is the container for all the activities to be carried out by a specific team or by a system.

Before you begin To perform this task, you must be in the IBM® Process Designer desktop editor.

Procedure 1. Open the Process Designer desktop editor. 2. Open a process application that contains a BPD. 3. Drag a lane from the palette and drop it onto the diagram. 4. In the Properties view, enter a name for the lane. 5. Optional: You can also associate a default team with the lane.When a user task is added to this lane, the initial assignment for the task is the default lane team. If you do not specify a default lane team, the default team is All Users. 6. Optional: You can also create a lane as a system lane, indicating that activities within it are to be completed by an IBM Business Process Manager system. To make a lane a system lane, select the lane in the diagram then select Is System Lane in the Properties view. Although you can create a system task in nonsystem lanes, any new tasks in the system lane are created as system tasks by default. After a system task is created, if you move the task to a non-system lane, for example a lane associated with a team, it retains a system task type. 7. To reorder lanes with respect to one another, right-click a lane and select Move Lane Up or Move Lane Down. 8. Click Save in the main toolbar. Parent topic:Creating a business process definition (BPD)

37

Adding activities to a BPD In a business process definition (BPD), you can include activities that represent logical work that a specific team or a system completes.

Before you begin To perform this task, you must be in the IBM® Process Designer desktop editor.

About this task When you add activities, follow these guidelines: - Ensure that activities represent logical units of work that are assigned to a participant of a process. - Make multiple concurrent workflow steps that are assigned to one responsible role into one activity or task. - Use verb-noun statements to label activities, such as Submit job requisition. - Apply a top-down, left-to-right flow to your BPD so that it is easier to read.

Procedure 1. Open the Process Designer desktop editor. 2. Open a process application that contains a BPD. 3. In the Designer view, click the Diagram tab. 4. Drag an activity from the palette and drop it onto the diagram. 5. In the Properties view, enter a name for the activity. 6. Click Save in the main toolbar.

What to do next After you add an activity to a BPD, you can change the type by selecting the activity and choosing the implementation in the properties. Parent topic:Creating a business process definition (BPD) Related information: Implementing activities in a BPD

38

Adding events to a BPD When modeling a process, you might want to model events that can occur at the beginning, during, or at the end of a runtime process (as opposed to activities that are carried out by participants in the process).

Before you begin To perform this task, you must be in the IBM® Process Designer desktop editor.

About this task An example of an event is a message received from an external system. You can specify the trigger type of an event and represent the event with a meaningful icon in your process diagram. Events in IBM BPM can be triggered by the passing of a due date, an exception, or the arrival of a message. The trigger determines the type of event that you choose to implement. For information about available event types and their triggers, see Modeling events. You can attach intermediate events (timer, message, and error events) to activities in your business process definitions (BPDs) to create boundary events or you can include intermediate events in the process flow by using sequence lines. Other events must be part of the process flow.

Procedure 1. Open the Process Designer desktop editor. 2. Open a process application that contains a BPD. 3. In the Designer view, click the Diagram tab. 4. Drag the event from the palette. If you want to create a boundary event by attaching an intermediate event to an activity, drop the event onto the activity node. To verify the attachment, select the activity. If the outline of the activity includes the event, the event is attached. By default, attached intermediate events are Error events. 5. Select the event. In the event properties, click the Implementation option. 6. Select the type of event from the available options. 7. For attached intermediate events, select Interrupt activity if you want the activity to close when the message is received. 8. In the Trigger section, you can select or create an undercover agent (UCA) to attach to the event. See the topic in the related tasks section. Each event must be associated with a UCA. When you run the process, the associated UCA carries out the required action when the event is triggered. Parent topic:Creating a business process definition (BPD) Related information: Creating an undercover agent

39

40

Modeling process execution paths by using sequence flows Use sequence flows to connect activities and other modeling constructs to establish the process flow.

Before you begin To perform this task, you must be in the IBM® Process Designer desktop editor.

Procedure 1. Open the Process Designer desktop editor. 2. Open a process application that contains a business process definition (BPD) in the Designer view. 3. From the palette, click to select the Sequence Flow tool. 4. In your process diagram, click the first modeling construct (normally the start event), and then click the construct that follows the start event in the process flow. The Sequence Flow tool connects the two items. 5. Continue creating sequence flows as needed. If more than one sequence flow leaves the same modeling construct, the first one you add is the default sequence flow. Subsequent sequence flows that originate from the same construct are only followed under certain conditions. To specify the conditions under which a nondefault path is followed: A. Select the sequence flow in the diagram. B. In the Behavior section of the Properties view, specify the condition under which the process execution follows this sequence flow. The default sequence flow is followed whenever the conditions specified for the non-default flows are not met. Conditions for all outgoing sequence flows other than the default sequence flow are required or mandatory. 6. When you are finished establishing the process flow, click the Selection Tool in the palette or press Esc to switch back to normal selection mode in the process diagram. Parent topic:Creating a business process definition (BPD)

41

Converging and diverging flows Gateways control the divergence and convergence of a sequence flow, determining branching and merging of the paths that a runtime process or case instance can take.

About this task You can think of inclusive and exclusive gateways as questions that are asked at a particular point in the flow. The question has a defined set of alternative answers, which act as gates. The process or case cannot proceed until a valid answer is provided. You can model questions by using JavaScript conditions, which are evaluated before the flow is allowed to proceed.Note:Case management functions are only available if you have IBM BPM Advanced with the Basic Case Management feature installed. You can model the following types of gateways in your process or service flow diagram: Table 1. Types of gateways that can be modeled in process diagrams Component icon

Gateway type Parallel (AND)

Inclusive (OR)

42

Description Use a parallel, diverging gateway when you want the process to follow all available paths. Use a parallel, converging gateway when you want to converge all available paths. Use inclusive, diverging gateway when you want to follow one or more available paths based on conditions that you specify. Use downstream of an inclusive diverging gateway to converge multiple paths into a single path after all the active paths completed their runtime execution. The inclusive join looks upstream at each path to determine whether the path is active, in which case it waits. Otherwise, it passes the token through without waiting.

Exclusive (XOR)

Event

Use to model a point in the process or service flow execution where only one of several paths can be followed, depending on a condition, or to model a point in process execution when the token for one of several incoming paths is passed through the gateway. Note: The exclusive gateways are the only gateways that can be implemented in human services. For more information, see Implementing exclusive gateways in client-side human services. Use to model a point in the process execution where only one of several paths can be followed, depending on events that occur. A specific event, such as the receipt of a message or timer event, determines the path to be taken. An event gateway must be modeled a certain way as described in Modeling event gateways.

Restriction: In human services, support for gateway implementation is provided for exclusive gateways only. Be aware of the following when using gateways: - After you drag a gateway from the palette to your diagram, you can choose any of the available gateway types. - When you model inclusive and exclusive gateways, if all conditions evaluate to false, the process follows the default sequence flow. The default sequence flow is the first sequence flow that you create from the gateway to a following activity, but you can change the default sequence flow at any time, as described in the following procedure. For more information about implementing inclusive and exclusive gateways, see Example gateways. To add gateways to a process or human service diagram:

Procedure 1. Drag a gateway from the palette onto the diagram.

43

2. In the box that displays over the gateway, type a name for the gateway. 3. Create the necessary sequence flow to and from the gateway. The default sequence flow is the first sequence that you create from the gateway to a following activity. For a gateway, you can change the default flow by reordering the sequence flow in the implementation properties. 4. Click the gateway in the diagram, and then click the General option in the properties. 5. In the Behavior section of the general properties, click the list and select a gateway type. The other fields described in the following table are optional:Table 2. Optional fields in the Behavior section of the general properties Field Name visible

Presentation Icon

Documentation Gateway Type

Description Displays the name that you provide for the gateway in the diagram. Clear this check box if you do not want the name displayed in the diagram. If you want to use an icon other than the default provided by IBM® Business Process Manager, provide the path name for the image that you want to use. This option is not applicable to exclusive gateways that are implemented in human services. Enter a description of the gateway. Ensure that the type of gateway you want to implement is selected from the list. The preceding table describes the types of gateways available. This option is not applicable to exclusive gateways that are implemented in human services.

6. Configure the implementation for the gateway. A. For inclusive and exclusive gateways, click the Implementation tab. For each outgoing sequence line, a condition (in JavaScript) is required that controls whether the path is followed. (For more information about the types of conditions that you can define, see Example gateways.) Ensure that the sequence flow shown as the Default Line is the one that you want the process or service flow to follow if all conditions evaluate to false. If not, reorder the lines until the one that you want is designated the default. Note: A default sequence flow does not have a condition. B. For event gateways, see Modeling event gateways. 7. Click Save in the main toolbar. Parent topic:Creating a business process definition (BPD)

44

Example gateways The following samples illustrate how to model several types of gateways. When modeling processes or case instances in IBM® Business Process Manager, you have several options for implementing gateways. See Converging and diverging flows to understand the available options and to see a sample implementation of a parallel gateway. Review the following samples to learn more about exclusive and inclusive gateways. - To implement an exclusive and inclusive gateway in a business process definition (BPD), you must declare variables for that BPD, as described in Declaring and passing variables. - To implement an exclusive gateway in a client-side human service, you must specify the JavaScript conditions that determine the path to be followed by the service flow, as described in Implementing exclusive gateways in client-side human services.Restriction: Support for gateway implementation in human services is provided for exclusive gateways only. Note: If you want complex expressions to be used in gateway definitions, you can enable an advanced editing feature in your preferences so that complex expressions can be entered and customized. The default preference settings do not have the advanced editing feature enabled. To enable the advanced editing feature, click File > Preferences, expand IBM BPM > Capabilities > IBM BPM Advanced Features, and then select Advanced Editors.

Sample exclusive gateways Use an exclusive gateway in a BPD or in a human service when you model a point in the flow in which only one of several paths can be followed. JavaScript conditions that you define for the sequence flows that emerge from the gateway determine which path is to be followed by the flow. In the Implementation properties, decisions are evaluated from top to bottom. The flow follows the first condition that evaluates to true. If all conditions evaluate to false, the flow follows the default sequence flow, which does not have a condition. - Sample exclusive gateway in a BPD - For example, you might have two exclusive gateways in a BPD diagram.Note: You can access the HR Open New Position BPD in the Hiring Sample process application or see Hiring Sample tutorial: Add event gateways and Hiring tutorial: Implement gateways in the Hiring tutorial section. In the sample and tutorial, the first gateway, named Need GM Approval?, determines which path to follow based on whether the submitted job requisition requires approval. To see how this works, click the gateway in the BPD diagram and then click the Implementation option in the properties. The approval options are then shown under the Decisions section.

45

Remember: To enable the advanced editing feature in your preferences, click File > Preferences, expand IBM BPM > Capabilities > IBM BPM Advanced Features, and then select Advanced Editors.

The Approval required path is followed to the Approve/reject requisition activity only when the tw.local.currentPosition.positionType variable is equal to "New". This logic ensures that those requisitions from Hiring Managers for new headcount are approved by General Managers before HR processing. If a position is not new, the process follows the default path to the Find job candidates activity. Notice in the BPD diagram that the default path is marked with a forward slash (/). The second gateway, named GM Approved?, determines which path to follow based on whether a new position is approved. To see how this works, click the GM Approved? gateway in the BPD diagram to select it, and then click the Implementation option in the properties. The approval information is then shown under the Decisions section. The Approved --> proceed to HR path is followed to the Find job candidates activity only when the tw.local.requisition.gmApproval variable is equal to "Approved". This logic ensures that those requisitions that require approval are approved before HR processing. If a requisition is not approved, the process follows the default path (Rejected path) to the Notify hiring manager activity. - Sample exclusive gateway in a human service - The following example shows the implementation of an exclusive gateway in a human service. To model the exclusive gateway in the service flow, JavaScript conditions that evaluate to true or false are defined in the implementation 46

properties of the gateway, under Decisions. A default sequence path is also specified in the Default Flow list, with no JavaScript condition associated with it. The flow follows the first condition that evaluates to true or, if all conditions evaluate to false, it follows the default sequence path.

The default sequence path is selected in the Default Flow list, and is followed to the Coach1 activity. Note that the default path is marked with a forward slash (/) sign in the diagram. The sequence flow to Coach2 evaluates to false.

Sample inclusive gateway Use an inclusive gateway in a BPD when you need to split or diverge the process along more than one path, and you want to follow one or more available paths based on conditions that you establish. Note: Inclusive gateways can follow a maximum of n-1 paths. So, if you model a conditional split with three paths, the process can follow two of those paths. Restriction: Support for implementing inclusive gateways in human services is not provided. For example, suppose that you want to model a process where the steps are different based on whether the customer type is new or existing. For new customers, you want activities 1 and 2 to be completed. For existing customers, only activity 3 is needed. You can use an inclusive gateway (split) for this type of process so that two activities are set for new customers and a third activity is set for existing customers.

47

With exclusive gateways, only one available path is followed from the gateway. With inclusive gateways or splits like the one described in the preceding example, one or more paths from the gateway can be followed. The inclusive split gateway in the preceding example determines the path or paths to follow based on the type of customer that is processed. The conditions for this split are configured in the implementation properties for the gateway as follows: - If the value of the tw.local.customerType variable is "New", the path to activity 1 is followed. - If the value of the tw.local.customerType variable is "New", the path to activity 2 is also followed. - If none of the preceding conditions evaluate to true, the path to activity 3 is followed. Using this logic, you are able to run two separate activities for new customers and a different activity when the customer is an existing one.

Parent topic:Creating a business process definition (BPD)

48

Implementing activities in a BPD Choose the implementation for each activity in your BPD and set the required properties.

Before you begin To perform this task, you must be in the IBM® Process Designer desktop editor.

About this task The following table lists the options available when you choose the implementation for an activity and provides a link to detailed information and procedures. To learn more about the types of tasks that are available, see Task types.Table 1. Implementation options available for activities in process diagrams Implementation option User Task

System Task

Description Select this option if an activity is to be started or completed by a user (human performer). For example, if an activity requires that managers enter employee data, choose User Task and select or create a clientside human service or a heritage human service to implement the task. Select this option if an activity is to be completed by an automated system or service. For example, if an activity requires integration with an external system, such as a database, choose System Task and select or create an Integration service to implement the task.

49

See... Building a client-side human serviceBuilding a heritage human service

Service types

Decision Task

Script

Subprocess

Linked Process

Select this option when you want a decision or condition in a business rule to determine which process implementation is started. For example, if you want Process Designer to implement an activity when a condition evaluates to true, choose Decision Task and select or create a decision service to implement the task. Choose this option if you plan to create a script to implement an activity. A Script activity runs a Java™ script. Use this option to encapsulate logically related steps within a parent process. Steps in a subprocess can directly access business objects (variables) from the parent process. No data mapping is required. However, unlike a linked process, a subprocess can be accessed and instantiated only from the parent BPD, and it is not reusable by any other process or subprocess. Therefore, use a subprocess for those implementations that are limited to a single business process definition (BPD). You can implement an activity by using a linked process. Linked processes encapsulate logically related steps within a process while retaining the high-level view of the parent process. Linked processes differ from subprocesses because they can be accessed and instantiated from processes other than a single parent process.

50

Service types

Using JavaScript variables and objects inside Process Designer Subprocess types

Working with linked processes

Event Subprocess

None

Use this specialized Modeling event subprocess to model subprocesses event-handling logic for a process or subprocess. It is triggered upon occurrence of a configured start event, and it is not connected to other steps through a sequence flow. It has access to the business objects (variables) of its parent process, and can encapsulate steps that use those variables. When triggered, an event subprocess can either interrupt the execution of its parent or can run in parallel. Select this option if you are not ready to associate an implementation. Use this option to create a temporary placeholder activity in your process diagram until an implementation is available. If you run a process that includes an activity with this option selected, the task completes immediately after it starts.

Tip: To learn how to make an activity conditional, see "Configuring conditional activities".

Procedure When the implementation that you want to use is created, such as a service, complete the following steps to select it: 1. Open the Process Designer desktop editor. 2. Open a process application that contains a BPD. 3. Select the activity that you want to use in the BPD diagram, and then go to the Implementation properties. 4. Under Implementation, select an option from the displayed list. For example, choose User Task if the implementation for the current activity is a human service with a coach. (The preceding table describes each available option.) Tip: To implement the task as either a client-side human service or a heritage human service, see Implementing a BPD activity as a human service.

51

5. Click Select to choose the implementation from the library. If the implementation does not yet exist, click New to create it. (The previous table provides instructions for creating implementations.) If you choose System Task for your implementation option, you must specify extra properties, as outlined in the following steps. 6. (System Tasks only) Select Delete task on completion if you want to run an automated service that does not require routing. When you select this check box, audit data for the task is not retained by the Process Server. By default, this option is disabled. 7. (User Tasks only) In the Task Header section, specify the following properties: Table 2. Properties in the Task Header section Property Clean State

Subject

Narrative

Action Select to clear the runtime execution state of an activity after it is complete. By default, this option is disabled. Enable this option only when you do not want to store execution data (such as variable values) for viewing after the process finished execution. Type a descriptive subject for the task that is generated in IBM Process Portal when you run the BPD. You can also use the IBM BPM embedded JavaScript syntax (for example, ) to express the subject. Type an optional description. You can also use the IBM BPM embedded JavaScript syntax to express the narrative. Restriction: Do not use JavaScript variable references in task narratives if you need the data to be available after the task completes. When a task is complete, IBM BPM removes the data for completed tasks to conserve space. Instead, store the data items in another location, such as a database.

8. (User Tasks only) In the Priority Settings section, specify values as needed.Tip: If you prefer to use a JavaScript expression with predefined variables to establish the priority settings, click JS for options. A. Under Priority, select one of the default priority codes from the list: Highest, High, Normal (the default), Low, or Lowest. B. Under Due In, enter a value in the text box and then choose Minutes, Hours, or Days from the list. (When you choose Days, you can use the text box after the list to specify hours and minutes.) You can also use the variable selector next to the text box to choose an existing variable from the library. At run time, the variable reflects the specified value for the time period. Select the required 52

option from the list: Minutes, Hours, or Days. C. Under Schedule, select an option from the list. For example, select 24x7 if you want 24 hours a day, seven days a week to be the time period in which the resulting tasks from the current activity can be due. You can leave the Schedule, Timezone, and Holiday Schedule fields set to (use default). If you do, the work schedule that is specified for the BPD is used. For more information, see "Setting the due date and work schedule for a BPD". D. Under Timezone, select the time zone that you want to apply to the tasks that result from the current activity. For example, you can select US/Pacific for users who work in California. E. Under Holiday Schedule, leave the setting at (use default) as described in the preceding note, or click JS if you prefer to use a JavaScript expression. Each holiday schedule is made up of a list of dates. If you choose JavaScript, you can enter either a String (or String-generated JavaScript) or a JavaScript that returns a TWHolidaySchedule variable. If you use a String, IBM BPM looks up the Holiday Schedule by name according to those rules. If you use a TWHolidaySchedule variable, IBM BPM assumes that the holiday schedule is appropriately specified. (Go to the System Data toolkit and open the TWHolidaySchedule variable to view its parameters.) 9. (User Tasks only) In the Processing Behavior section, select Automatically flow to next task if you want the next task in the sequence to run automatically. - Implementing a BPD activity as a human service If an activity in the business process definition (BPD) is to be completed by a user, you can implement the activity as a client-side human service or a heritage human service. - Creating loops for a BPD activity When you want the runtime task that results from a BPD activity to be run more than once, you can create a loop. You can create simple loops and multi-instance loops in IBM Business Process Manager. Parent topic:Creating a business process definition (BPD) Related tasks: Setting the work schedule for a BPD Automatically starting the user's next task Related information: Service types Configuring conditional activities

53

Implementing a BPD activity as a human service If an activity in the business process definition (BPD) is to be completed by a user, you can implement the activity as a client-side human service or a heritage human service.

Before you begin To perform this task, you must be in the IBM® Process Designer desktop editor.

About this task To implement the activity as a service:

Procedure 1. Open the Process Designer desktop editor. 2. Open a process application that contains a BPD. 3. Select the activity that you want implemented in the BPD diagram, and then go to the Implementation properties. 4. From the Implementation list, select User Task, and then click Select next to Default Human Service. 5. From the corresponding list, select the client-side human service or the heritage human service to implement the user task. If the human service does not exist, click New and complete the wizard steps to create the human service. 6. On the General tab, update the name of the user task as required, and then click Save.Back in the Diagram view, when you double-click the task in the BPD: - The Process Designer web editor opens if the task is associated with a clientside human service. - The Process Designer desktop editor opens if the task is associated with a heritage human service.

Parent topic:Implementing activities in a BPD Related information: Client-side human services Difference between client-side human services and heritage human services

54

Creating loops for a BPD activity When you want the runtime task that results from a BPD activity to be run more than once, you can create a loop. You can create simple loops and multi-instance loops in IBM® Business Process Manager. Prerequisite: To create loops, you must be in the IBM Process Designer desktop editor. IBM Business Process Manager provides several ways to create and implement loops. For example, you can include a script component in a service that iteratively processes records that you retrieve from a database until all records are processed. Since you can include JavaScript throughout your implementations, you can easily develop the logic required to repeat an action until a certain condition is true. In addition to implementing loops with scripts, the activities that you add to your BPDs can be configured for simple and multi-instance loops, as described in the following table. When you want the runtime task that results from an activity to be run more than once, you can configure loop behavior for that activity. Table 1. Loop types available for loop configuration Loop type Simple loop

Multi-instance loop

Description When you model a BPD activity with simple loops, the required number of instances is dynamically created, up to the loop maximum value that you specify. A simple-loop activity is run sequentially until the last instance of the activity is run. When you run an activity configured for simple loops, a single token is generated and used for each instance of the activity, which, in effect, recycles the runtime task. A multi-instance loop dynamically runs multiple unique instances of the same BPD activity sequentially or in parallel. When you run an activity configured for multi-instance loops, a unique token is created for each instance of the activity. (For more information about tokens, see Inspector reference.)

- Configuring a BPD activity for simple loops Follow these steps to configure a BPD activity for simple loops. - Configuring a BPD activity for multi-instance loops Using multi-instance loops, you can dynamically run multiple unique instances of the same activity sequentially or in parallel. When you run a BPD activity that is configured for multi-instance loops, a unique token is created for each instance of the activity. Parent topic:Implementing activities in a BPD

55

56

Configuring a BPD activity for simple loops Follow these steps to configure a BPD activity for simple loops.

Before you begin To perform this task, you must be in the IBM® Process Designer desktop editor. Restriction: Ad hoc start events are not supported in simple loop activities. If you are using looping, do not define ad hoc actions for Process Portal users to start.

About this task When you model an activity with simple loops, the required number of instances is dynamically created, up to the loop maximum value that you specify. A simple-loop activity is run sequentially until the last instance of the activity is run. When you run an activity configured for simple loops, a single token is generated and used for each instance of the activity, which, in effect, recycles the runtime task.

Procedure 1. Open the Process Designer desktop editor. 2. Open a process application that contains a BPD. 3. Select the activity that you want to configure in the BPD diagram. 4. Click the General option in the properties. 5. Under Behavior, select the Simple Loop option from the Loop Type list. 6. Under Simple Loop, type a value in the Loop Maximum box. This value sets the maximum number of instances that can be created at run time. If you declare a variable that can be used for this setting, click the variable icon to select it or type the variable name into the Loop Maximum box. 7. In the Loop Condition box, type an optional JavaScript condition to dictate the runtime loop behavior. A condition is evaluated before any instances are created from the activity. If the condition is not met, the loop configuration does not occur. 8. Save your changes.

Results When you configure an activity for simple loops, the activity includes the indicator

shown in the following image: Parent topic:Creating loops for a BPD activity

57

Configuring a BPD activity for multi-instance loops Using multi-instance loops, you can dynamically run multiple unique instances of the same activity sequentially or in parallel. When you run a BPD activity that is configured for multi-instance loops, a unique token is created for each instance of the activity.

Before you begin To perform this task, you must be in the IBM® Process Designer desktop editor. Restriction: Ad hoc start events are not supported in multi-instance loop activities. If you are using looping, do not define ad hoc actions for Process Portal users to start.

Procedure 1. 2. 3. 4. 5. 6.

Open the Process Designer desktop editor. Open a process application that contains a BPD. In the BPD diagram, select the activity that you want to configure. In the properties, select General. Under Behavior, select Multi-instance Loop from the Loop Type list. Under Multi-instance Loop, type a value in the Start Quantity box. This value sets the number of instances that are created at run time. To specify a variable that can be used for this setting, click the variable icon to select it or type the variable name into the Start Quantity box. Tip: For information about how to associate each loop activity instance with a specific item in a list, see Associating loop activity instances with different items. 7. From the Ordering list, select one of the following options: Option Run Sequential

Description Resulting instances are run sequentially until the last instance of the activity is complete. Run in Parallel Resulting instances are run at the same time until all instances are finished or until the condition that you specify is met. 8. For parallel ordering, select one of the following options from the Flow Condition list: Option Wait for all to finish (All)

Description Looping continues until all resulting instances of the activity are finished.

58

Conditional Wait (Complex)

Looping continues until the condition that you specify in the following step is met. 9. For complex flow conditions, type the JavaScript to implement that condition in the Complex Flow Condition box. 10. If you want active instances of the activity to be canceled when the preceding condition is met, select Cancel Remaining Instances.The runtime behavior of a multi-instance loop depends on how its task is implemented. The behavior is different when the task content contains server scripts only and when it also includes services. For example, a loop with Ordering selected to Run in Parallel, with a valid complex flow condition, and Cancel Remaining Instance set to true, runs as follows: - Loop content contains server scripts only: If you specify only server scripts in the multi-instance loop task content, the various instances of the loop run sequentially. Therefore, all instances run in sequence, they all run to their end, and at the end of all task instances the exit conditions are verified, again sequentially. - Loop content contains Human, Decision, or System services: If the loop task content contains a Human, Decision, or System Service, then the tasks instantiate in parallel within their own thread. In the example of the System service, if an exit condition is set, upon completion of the System service task, the result is given back to the multi-instance loop. Then, the condition is evaluated and the multi-instance loop task completes, which ends all other still running loop instances. 11. Save your changes. Parent topic:Creating loops for a BPD activity

Associating loop activity instances with different items About this task You can configure activity instances in multi-instance loops so that each instance corresponds to one specific item in a list. For example, if you have five instances of an activity and five orders in a list, you might want to associate each instance with an order in the list. To set up the activity instance-item association, the following key settings are required: - As a prerequisite, you must already have defined a private variable that holds the list of items that you want to iterate through, for example, tw.local.ListofItems. This variable is used in the built-in tw.local.ListofItems.listLength JavaScript function, where .listLength calculates the length of the item list. - You associate each activity instance with a specific item in the list by using the tw.local.ListofItems[tw.system.step.counter] JavaScript, where [tw.system.step.counter] specifies which item to be retrieved from the list.

Procedure 59

1. In the BPD diagram, select the activity that you want to configure. 2. In the properties, select General. 3. Under Behavior, select Multi-instance Loop from the Loop Type list. 4. Under Multi-instance Loop, enter tw.local.ListofItems.listLength in the Start Quantity box. 5. On Data Mapping, under Input Mapping, select, or type the following input string: tw.local.ListofItems[tw.system.step.counter] 6. For the Ordering and Flow Condition settings, refer to steps 7 and 8 in the procedure described earlier. 7. Save your changes.

60

Assigning teams to BPDs and lanes Assign teams of users that can start activities, and teams that can work on activities in Process Portal. You can assign a team of instance owners for a BPD, or you can assign teams for individual activities and lanes.

Before you begin To perform this task, you must start the Process Designer desktop editor. For information about how to create a team, see Creating a team.

About this task You can assign teams to activities that are implemented as user tasks (including ad hoc activities), to lanes, and as instance owners in the Overview page of the BPD editor. Teams that are assigned to activities and lanes determine which users can work on tasks in Process Portal. If a team is assigned to a user task activity, members of that team can work on that task in Process Portal. If a team is assigned to a lane, members of that team can work on all the tasks that are part of that lane. If both a user task activity and the lane in which it is contained have teams that assigned to them, the team that is assigned to the activity is used. If a user task implements an ad hoc activity, members of the team that is assigned to the lane or members of a task-specific team can work on the task. The instance owners team and lane teams are authorized to perform actions that are related to an ad hoc activity, such as starting a manual activity. Members of the instance owners team can start the task in Process Portal, and can start, disable, and enable ad hoc activities in the BPD. For instances that they own, they can reassign user tasks, set their due dates and the priority of tasks.

Procedure To assign a team of instance owners to a BPD: 1. Open the Process Designer desktop editor. 2. Open the process application that contains the business process definition (BPD). 3. In the BPD Overview, select a team for Instance owners, or create a new team. To assign teams to lanes: 1. In the BPD diagram, click the lane in which you want to make the assignment. 2. In the Behavior section of the properties, click Select to choose the team that you want to use as the default team for this lane. You need a default lane assignment to ensure that any activities that are not otherwise routed have an automatic default assignment. By default, the All Users team is assigned to each lane in the BPD. You can use this default team for running and testing your BPD in the Inspector. The All Users team includes all users in the system who are members of the tw_allusers security group.Note: If the default team assigned to the lane that is currently used for activity is changed, the team filter service definitions are removed from the Assignments tab. 3. Choose the team from the library.

61

To assign teams to activities, see Assigning teams to BPD activities 1. Click Save in the main toolbar. Parent topic:Creating a business process definition (BPD)

62

Assigning teams to BPD activities For any activity with a service implementation, you can designate the users who receive the runtime task by using the Assignments page in the properties for that activity.

Before you begin To perform this task, you must be in the IBM® Process Designer desktop editor.

About this task Note: Assignment options are available only for those activities with a BPM service implementation.

Procedure 1. Open the Process Designer desktop editor. 2. Open a process application that contains a business process definition (BPD). 3. Click an activity in a BPD diagram to display its properties. 4. Go to the Assignments page in the properties view. 5. From the Assign To list, choose one of the following options:Table 1. Assignment Options Option Lane

Team

Routing Policy (Deprecated) List of Users (Deprecated)

Description Assigns the runtime task to the team associated to the swimlane in which the selected activity is located (the default selection). If you select this option, you can use a team filter service to dynamically eliminate users from being assigned to the activity. Assigns the runtime task to a team. If you select this option, you can either specify a static team or use a team retrieval service to dynamically select a suitable set of users. In addition, you can use a team filtering service to remove unsuitable users from the team. Assigns the runtime task according to the policy that you establish. Assigns the runtime task to an ad hoc list of users.

63

Custom (Deprecated)

Assigns the runtime task according to the JavaScript expression that you provide in the corresponding field. To select one or more variables for your expression, click the variable selection icon next to the field. The JavaScript expression produces results such as USER: or ROLE:, where user_name is the name of an IBM BPM user (such as author) and group_name is the name of an IBM BPM security group (such as tw_authors).Note: Complex JavaScript expressions can be typed in or pasted into the Expression field and can be customized as required. More valid expressions can be chained together to produce a complex JavaScript expression, for example tw.local.isWeekendCrew?"ROLE:Week endManagers":"ROLE:Managers".

Important: To show up in the Team Performance dashboard, tasks must be assigned to a Team or a team Lane. Tasks that are assigned to the deprecated options are not displayed on the Team Performance dashboard. 6. Optional: From the Experts Team list, select the team that you want to associate with the selected activity. 7. If you selected Assign ToTeam you must assign a team. A. To define a new team, click New, provide a name, and complete the team properties. For more information about the team properties, see Creating a team. B. If you want to select an existing team, click Select, then choose a team from the list. C. If you want to specify a fixed team name or a team that is not defined yet, enter the name as a literal value, for example, damageAssessors. D. If you want the team to be selected by the value of a local or environment variable, specify the name of the variable, for example, tw.local.dynamicTeamName. 8. Optional: If you selected Assign ToTeam or Assign ToLane the Team Filter Service section is displayed. If you want to use a team filter service to eliminate certain users before the user distribution is applied, complete the following steps. A. To assign a Team Filter Service, either click Select to select an existing team filter service or click New to define a new one. If you select New, perform Setting up a team filter service. B. If the team filter service that you selected or defined requires parameters from the application, a Team Filter Service Input Mapping section is displayed. For each required service variable, enter the corresponding process variable name, for example tw.local.estimatedClaimAmount or tw.system.user.id .

64

9. From the User Distribution list, choose one of the following options:Table 2. User Distribution Option None Last User

Load Balance

Round Robin

Description IBM BPM assigns the runtime task to all potential users (the default setting). Assigns the runtime task to the user who completed the activity that immediately precedes the selected activity in the swimlane. Do not select this option for the first activity in a lane unless the activity is a service in a toplevel BPD and a Start Event is in the lane. In this case, the runtime task is routed to the user who started the BPD. From the potential users who can receive the runtime task, IBM BPM assigns to the users who have the fewest number of open tasks, regardless of presence. From the potential users who can receive the runtime task, IBM BPM assigns to users in a round-robin fashion. For example, if the users in the Call Center team must receive the runtime task, IBM BPM assigns each task (created by each process instance) in a series - to one user in the team after another.

- Assigning an activity to a dynamically retrieved team If you do not want to assign an activity to a static team, you can define a team retrieval service that dynamically returns a set of users and managers. - Setting up a routing policy (deprecated) One of the options when routing the runtime tasks that are generated by activities, is to establish a routing policy. - Defining rules with a routing policy (deprecated) When you establish a Routing Policy for a BPD activity, you establish rules to determine the recipients of the activity as a runtime task. - Assigning an activity to an ad hoc list of users (deprecated) An activity can be assigned to an ad hoc user list if the user group is defined dynamically when a business process definition (BPD) instance is running. Parent topic:Creating a business process definition (BPD)

65

Assigning an activity to a dynamically retrieved team If you do not want to assign an activity to a static team, you can define a team retrieval service that dynamically returns a set of users and managers.

Before you begin To perform this task, you must open the Process Designer desktop editor.

About this task You can define a new team retrieval service either when you define a team, or when you assign an activity to a team.

Procedure If you are working with a business process definition (BPD), and want to assign an activity to a dynamically retrieved team, complete the following actions. 1. Open the Process Designer desktop editor. 2. Open a process application that contains a BPD. 3. Open the diagram of your BPD and select the activity that you want to assign to a team that is defined by a team retrieval service. 4. Go to the Assignments page in the properties view. 5. From the Assign To list, select Team.Tip: The Assign toLane option can also be resolved by a team retrieval service if the team that is assigned as the default team for the lane is a dynamically resolved team. 6. To assign the activity to an existing dynamically defined team, click Select then select the name of the dynamically defined team. 7. To assign the activity to a new dynamically defined team, click New, provide a team name, then follow the instructions described in Setting up a team retrieval service.

Results The team's members are determined dynamically by the appropriate team retrieval service. Parent topic:Assigning teams to BPD activities

66

Setting up a routing policy (deprecated) One of the options when routing the runtime tasks that are generated by activities, is to establish a routing policy.

Before you begin To perform this task, you must be in the IBM® Process Designer desktop editor. Before you can configure a routing policy, you must declare variables for your BPD.

About this task When you define a policy, the users who receive the runtime task are determined by the conditions that you specify.

Procedure 1. Open the Process Designer desktop editor. 2. Open a process application that contains a business process definition (BPD). 3. Open the diagram of your BPD and select the activity that you want to route. Note: The activity that you choose must already have an attached service. 4. Go to the Assignments page in the properties view. 5. From the Assign To list, select Routing Policy (Deprecated). 6. Under Routing Conditions (If), click Add a column to select the variable to use to begin specifying conditions.When defining routing conditions, you create a table in which each column represents a variable and each row represents a rule. 7. From the displayed list, choose the variable for which you want to specify a condition. 8. In the first field in row 1, enter the value to compare to the variable.For example, if you choose a variable called customer (String) in the preceding step and that variable holds customer names, enter a customer name in the field. 9. If you want to add another variable to the routing condition, click Add a column and choose a variable from the displayed list. Enter the value to compare to the second variable.The following examples illustrate the syntax for possible values in the variable columns: Table 1. Routing conditions Enter...

To match... The exact string, ok (no quotation marks) Any number greater than 100 Any number less than 100 All numbers except 3

"ok" >100 Implementation > Activity Behavior. B. Indicate how the activity is started. - If the activity is started by the system, select Automatically by the process. - If the activity must be started manually by the user, select Manually by the user. C. Indicate whether the activity must be completed. - If the activity must be completed before the process can complete, select Yes. The activity is required. - If the activity does not have to be completed for the process to complete, select No. The activity is optional. D. If the activity can be run multiple times, select Repeatable: The activity can be invoked multiple times. E. If the activity is started by the system, and must be hidden from users, select Hidden. This is a background activity that users will not see. F. If preconditions must be met before the user or system can start the activity, select There are preconditions that must be met before the activity can be performed, and specify the conditions that must be met. 1. If there are multiple conditions, use the Match field to select whether all must evaluate to true, or whether it is sufficient for any one of them to be true. 2. To specify the conditions by selecting a variable, a comparison operator, and another variable or literal value, use the default form. A. Click the variable selection icon to select from a list of variables. B. In the next field, select the type of comparison that is required, such as is equal to and not equal to. Tip: The choices that are available depend on the type of the variable that you selected. For example, for numeric, date, and time variables, you can also select is less than, is less than or equal to, is greater than, or is greater than or equal to. C. In the next field, either enter a literal value or the name of a variable, or click the other variable selection icon to select from a list of variables.

77

3. To specify the conditions as JavaScript expressions, click js to switch to the JavaScript expression form, and enter the JavaScript expression for the condition. To return to the default form, click js again. 4. To add more conditions, click the add icon. - Example: Starting an unstructured (ad hoc) activity (JavaScript API) This example shows you how to start an unstructured (ad hoc) activity. Parent topic:Creating a business process definition (BPD)

78

Example: Starting an unstructured (ad hoc) activity (JavaScript API) This example shows you how to start an unstructured (ad hoc) activity.

Before you begin To start an unstructured activity, the user must be a member of one of these groups: - BPM admin - Process/case admin - Process/case instance owner - Default lane team of the corresponding lane An authorization check is performed by the REST API only when starting an unstructured activity.

Procedure To start an unstructured (ad hoc) activity, complete the following steps. 1. Retrieve a list of matching unstructured activities and their IDs on a TWProcessInstance object. On the ActivityListItem object there is a list of available actions for the current user (the user that executed the retrieveActivityList() call), as well as the ID of the activity. Refer to the description of the TWProcessInstance object in JavaScript API for IBM Process Designer. - Set the hiddenFilter parameter to retrieve hidden activities. - Set the checkAuthorization parameter to true to receive only those results that the current user is authorized to view for the process or case instance. log.info("querying for piid: " + tw.local.piid); var pi = tw.system.findProcessInstanceByID(tw.local.piid); log.info("found process instance: " + pi);

var activitiyListProperties = new tw.object.ActivityListProperties();

var activityListFilter = new tw.object.ActivityListFilter(); activityListFilter.executionStateFilter = ["READY"];

activitiyListProperties.filters = new tw.object.listOf.ActivityListFilter(); activitiyListProperties.filters.insertIntoList(0, activityListFilter);

log.info("querying for activity list ..."); tw.local.activities = pi.retrieveActivityList(activitiyListProperties) log.info("activities found: " + tw.local.activities);

tw.local.aiid = // get the id of the activity you want to start (and 'actions' contains 'ACTION_START_ACTIVITY')

2. When you have the ID of the unstructured activity, use the findActivityInstanceByID() call to retrieve the instance of the activity. Then call start(...) to start the instance. Refer to the description of the

79

TWBPDSystemNamespace object in JavaScript API for IBM Process Designer. The optional parameter taskOwnerUserId reassigns the task to the specified user id.

This feature works only for unstructured activities with a user task implementation. Refer to the description of the ActivityInstance object in JavaScript API for IBM Process Designer. log.info("querying for aiid: " + tw.local.aiid); var ai = tw.system.findActivityInstanceByID(tw.local.aiid); log.info("starting activity with id: " + tw.local.aiid); ai.start();

Parent topic:Creating an unstructured (ad hoc) activity

80

Subprocess types Subprocess is an option for encapsulating logically related steps within a parent process. Steps in a subprocess can directly access business objects (variables) from the parent process. No data mapping is required. However, unlike a linked process, a subprocess can be accessed and instantiated only from the parent BPD, and it is not reusable by any other process or subprocess. A subprocess represents a collection of logically related steps contained within a parent process. You can view a subprocess as a single activity, providing a simplified, high-level view of the parent process, or you can drill into the subprocess for a more detailed view of its contents. A subprocess can be embedded within another subprocess. To drill down into a collapsed subprocess and view the contents, double-click the subprocess activity in the parent. To go back to the parent process from within a subprocess or event subprocess, use the navigation in the upper left corner of the diagram. To return to a parent process from a linked process, use the menu above the canvas. Subprocesses can contain swimlanes that are distinct from the parent process. For example, activities in your subprocess can be carried out by a set of participants that is different from the set of participants that carry out the activities in the parent process. Like other activities, subprocesses can be configured to run multiple times within the execution of the parent process by configuring looping behavior on the subprocess activity element in the parent process. There are three types of subprocesses that you can model in a BPD. Their characteristics are described in the following table. Table 1. Types of subprocesses that can be modeled in a business process definition Implementation

Description

Characteristics

81

Variable scope

Subprocess

A non-reusable subprocess that exists only within the parent process.

Linked process

A call to another reusable process.

Each subprocess must contain at least one start event with an implementation type of None.Activity names must be unique with respect to the top-level process activities, and all other subprocesses and event subprocesses under the same toplevel process.

Inherits variables from the parent process and can contain local private variables visible only within the subprocess.Variabl e names declared in a subprocess cannot be the same as variable names declared in any of its parent processes. If there are multiple layers of embedding, with subprocesses contained within other subprocesses, variable names must be unique throughout the entire subprocess hierarchy. The process called Variable data is by the linked local to each process activity can process, therefore contain multiple data mapping is start events, but required to pass must contain at data into and out of least one start event the linked process. with an implementation type of None.

82

Event subprocess

A specialized type of non-reusable subprocess that is not part of the normal sequence flow of its parent process, and which might occur zero or many times during the execution of the parent process.

Must contain a single start event, which can be one of:TimerMessageEr rorEvent subprocess execution can interrupt parent process or can run in parallel. Activity names must be unique with respect to the toplevel process activities, and all other subprocesses and event subprocesses under the same top-level process. Boundary events are not supported on an event subprocess.

Inherits variables from the parent process and can contain local private variables visible only within the subprocess.Variabl e names declared in an event subprocess cannot be the same as variable names declared in any of its parent processes. If there are multiple layers of embedding, with event subprocesses contained within other subprocesses, variable names must be unique throughout the entire subprocess hierarchy.

- Modeling non-reusable subprocesses A subprocess is a logical collection of activities that exists only within its parent process. Grouping related process elements in a subprocess simplifies the view of the process. A subprocess hides the complexity of individual step details until the subprocess activity is expanded. - Working with linked processes A process can call another process through a linked process activity. When the linked process activity is triggered at run time, the linked process is run. After the linked process is completed, the parent process resumes execution. When you group together related activities in a separate BPD, instead of in a subprocess, you can reuse that process in other processes that share that set of activities. For example, the steps for creating a customer account might be common to several different processes. If you group these steps together in a Create Customer Account process, you can use linked process activities to call this process from all processes that require it. - Modeling event subprocesses Event subprocesses are triggered by an event that occurs in the parent process. Event subprocesses are similar to other subprocesses in that they are contained within a parent process, and are not reusable outside of that process. They are unlike other subprocesses in that they are not connected to other activities in the process by incoming or outgoing connections, but are instead triggered by an event or timer.

83

Parent topic:Creating a business process definition (BPD)

84

Modeling non-reusable subprocesses A subprocess is a logical collection of activities that exists only within its parent process. Grouping related process elements in a subprocess simplifies the view of the process. A subprocess hides the complexity of individual step details until the subprocess activity is expanded.

About this task Subprocess activities are represented in the process diagram or case type activities

diagram by an activity element with an expandable subprocess marker: Note:Case management functions are only available if you have IBM BPM Advanced with the Basic Case Management feature installed.

Procedure 1. For a business process, open the parent business process definition (BPD) in the Process Designer. A. Drag an activity from the palette onto the diagram area, and enter the name of the activity in the highlighted box. B. In the Implementation tab of the Properties view, select Subprocess. The visualization of the activity in the diagram is updated to reflect the subprocess activity type. C. Double-click the subprocess activity to add elements to the subprocess. The subprocess expands in the editor. 2. For a business process or case type, drag elements from the palette onto the canvas. By default, your new subprocess contains a start event and an end event. Subprocesses must contain at least one start event with an implementation type of None. Names of activities that you create in your subprocess must be different from the names of activities in the top-level process. The names must also be different from any subprocess under the same top-level process. For a business process, swimlanes or phases that you add to your subprocess are independent. They are not part of the swimlanes and phases that are contained in the parent business process definition. 3. Like other activities, you can configure your subprocess to run the subprocess steps multiple times. Select the subprocess activity in the parent process and set the repeating behavior in the General tab. 4. Subprocesses have access to all of the variables that are defined in the parent process. You do not need to map data to pass data into or out of the subprocess. However, you can Modeling subprocess data that are only available to the subprocess (and any subprocesses it contains).

What to do next In a business process, to return to the parent business process definition, use the 85

navigation in the upper left of the canvas. Parent topic:Subprocess types

86

Working with linked processes A process can call another process through a linked process activity. When the linked process activity is triggered at run time, the linked process is run. After the linked process is completed, the parent process resumes execution. When you group together related activities in a separate BPD, instead of in a subprocess, you can reuse that process in other processes that share that set of activities. For example, the steps for creating a customer account might be common to several different processes. If you group these steps together in a Create Customer Account process, you can use linked process activities to call this process from all processes that require it.

About this task Linked processes encapsulate logically related steps within a process while retaining the high-level view of the parent process. However, linked processes differ from subprocesses because they can be accessed and instantiated from processes other than a single parent process. In previous product releases, linked processes were known as nested processes. Linked process activities are represented in the process diagram by an activity element with a thick border and an expandable subprocess marker.

Procedure 1. Open the parent business process definition (BPD) in the Process Designer. 2. Drag an activity from the palette onto the diagram area, and type the name of the activity in the highlighted box. 3. In the Implementation tab of the Properties view, select Linked Process. The visualization of the activity in the diagram is updated to reflect the Linked Process activity type. 4. Specify another process to call during the execution of your process. - To select an existing process, click Select, and choose the business process definition. - To create a reusable process: A. Click New. B. Enter a name for the new process and click Finish. In the editor, continue to specify this new process definition, or return to the parent process. - You can also Calling a linked process dynamically by using a variable defined in the parent process. 5. In the parent process, connect the linked process activity to other elements in the process flow. 6. Variables in a linked process activity are local to the linked process. If you want to pass data into or out of a linked process activity, you must map the inputs and outputs of your linked process to the inputs and outputs of the linked process activity in the parent. Complete one of the following steps in the Data Mapping tab of the Properties view for the linked process activity: - If you declared variables in the parent process that have the same names and data types as the input and output variables in the linked process, use auto-

87

mapping to have the inputs or outputs of the linked process automatically mapped to variable defined in the parent process. - If the variables declared in the parent process do not match the variables of the linked process inputs or outputs, you can manually select the variables to map. - Calling a linked process dynamically When you use a linked process as the implementation for an activity, you can use an advanced option in the implementation properties to supply a predefined variable to dynamically call one of many linked processes, depending on your needs. Parent topic:Subprocess types

88

Calling a linked process dynamically When you use a linked process as the implementation for an activity, you can use an advanced option in the implementation properties to supply a predefined variable to dynamically call one of many linked processes, depending on your needs.

About this task To use the dynamic option for a linked process, complete the following tasks first: - Create a variable of type String in the parent process to hold the name of the linked process that you want to run. Your parent process must also include the logic to determine the value of this variable at run time. For example, the parent process can include logic to set the value of this variable based on user input. - Establish the input and output variables for each potential linked process so that the parent process runs as expected regardless of which linked process is called. To meet this requirement, the variables in all potential linked processes must be the same. To map variables from the parent process to the linked process, follow the steps described in Working with linked processes. - Dependencies might exist between process applications and toolkits, as well as between toolkits and other toolkits. For example, ProcessApp PA1 might depend on Toolkit TK1, which in turn might depend on Toolkit TK2. This creates a dependency chain: PA1 -> TK1 -> TK2. In order for the search to be started at the beginning of the dependency chain (in PA1), the name of the invoked business process definition (BPD) must be prefixed with a double slash (//). If a BPD in TK1 invokes a BPD dynamically without the double slash prefix, it will find only BPDs down the dependency chain (that is, in TK1 and TK2, but not in PA1). Restriction: The Diagram tab on the Process Performance dashboard can drill down into subprocesses and statically linked processes that are defined in the business process definition (BPD). It cannot drill down into dynamically linked processes that are called by the process at run time. To configure an activity to dynamically call one of many potential linked processes, complete the following steps:

Procedure 1. 2. 3. 4. 5.

Open the parent BPD in the Process Designer. Click the activity that you want to work with in the BPD diagram. Click the Implementation tab in the properties. Under Implementation, select the Linked Process menu option. Click Select to choose one of the predefined linked BPDs from the library.You must initially select one of the predefined linked BPDs for the dynamic configuration to function properly. 6. Click the Data Mapping tab in the properties.Because you already created the input and output variables for the linked process, the Data Mapping tab for the activity in the parent process includes those variables. 7. Under Input Mapping, click the auto-map icon in the upper-right corner, and then click the auto-map icon in the upper-right corner of the Output Mapping section.

89

8. Click the Implementation tab in the properties. 9. Click the indicator next to the Processing Behavior section heading to expand the section. 10. Click the variable icon next to the Dynamic Sub-Process field to choose the previously defined variable that provides the name of the selected process.Note: At run time, the value of this variable cannot be null and it must exactly match the name of an existing BPD. 11. Save the configuration. Parent topic:Working with linked processes

90

Modeling event subprocesses Event subprocesses are triggered by an event that occurs in the parent process. Event subprocesses are similar to other subprocesses in that they are contained within a parent process, and are not reusable outside of that process. They are unlike other subprocesses in that they are not connected to other activities in the process by incoming or outgoing connections, but are instead triggered by an event or timer.

About this task The event subprocess is a specialized subprocess that you can use to model eventhandling logic for a process or subprocess. It is triggered upon occurrence of a configured start event, and as a result it is not connected to other steps through sequence flow. It has access to the business objects (variables) of its parent process and so can encapsulate steps that use those variables. When triggered, an event subprocess can either interrupt the execution of its parent or it can run in parallel. You can use event subprocesses to handle exceptional process flows within your process. For example, an event subprocess can be used to handle an out-of-stock situation that arises during an order-fulfilment process. The out-of-stock event in the parent process triggers the start event in the event subprocess, which contains activities to order more stock or to check supplies at other locations. An event subprocess can have only one start event. The start event implementation is represented visually in the event subprocess activity in the parent process. It can have any of the following implementation types:Table 1. Event subprocess implementation types and visualizations Start event implementation type Event subprocess visualization Error

Message

Timer

- Message event subprocesses are triggered by a message event that often originates from outside the business process definition (BPD) in which the event subprocess is contained. A message start event might be used in a situation similar to the situation described previously, where a message, such as an out-ofstock message, is received by the event subprocess and triggers a sequence of activities. - A timer start event might be used to model the steps to take when an activity within the parent process is not completed after a specified amount of time. For example 91

if a requested item cannot be located within a certain amount of time, the out-ofstock subprocess can be triggered by a timer start event. - An error start event might be triggered when something goes wrong in the process, for example, the order fulfilment system is non-responsive. Error start events can be triggered only from within the parent BPD or its subprocesses. A parent process cannot complete until all active event subprocesses are complete, unless the parent is terminated by a terminate end event. A terminate end event in an event subprocess terminates only the activities that are contained within that event subprocess. Boundary events cannot be attached to event subprocesses. To handle exceptions within an event subprocess, for example, errors that arise during the event subprocess execution, event subprocesses can themselves contain event subprocesses. To add an event subprocess to your BPD:

Procedure 1. Open the parent business process definition (BPD) in the Process Designer. 2. Drag an activity from the palette onto the diagram area, and type the name of the activity in the highlighted box. 3. In the Implementation tab of the Properties view, select Event Subprocess. The visualization of the activity in the diagram is updated to reflect the event subprocess activity type. By default, new event subprocesses are assigned an error start event. 4. To change the start event type and properties and to add activities to the event subprocess, double-click the event subprocess activity to expand it. 5. Select the start event and, from the Implementation tab in the properties view, select a new implementation type from the list. 6. The start events for event subprocesses can be interrupting or non-interrupting. When triggered, event subprocesses with an interrupting start event terminate all activities in the parent process. Activities in an event subprocess with a noninterrupting start event run in parallel with the parent process. You can specify whether the start event of the event subprocess is interrupting or non-interrupting by selecting or by clearing Interrupt Parent Process. Note: Error start events in an event subprocess always interrupt the parent process and cannot be set to non-interrupting. 7. To configure an event subprocess to be repeatable, select Repeatable? on the Implementation tab. When you select this property, the event subprocess might run several times during the execution of a process, and might have multiple instances that run in parallel.Note: Unlike subprocesses, looping behavior is not supported for event subprocesses. 8. Drag elements from the palette onto the canvas. The names of the activities that you create in your subprocess must be different from the names of the activities in the top-level process or any other subprocess or event subprocess under the same top-level process. Any swimlanes or phases that you add to your subprocess are independent from the swimlanes and phases that are contained in the parent BPD. 92

9. Like subprocesses, event subprocesses have access to the data of the parent process. Data mapping is not required to pass data into or out of the event subprocess. You can also declare private variables within the event subprocess itself, which are not visible to the parent BPD. See Modeling subprocess data.

What to do next To return to the parent BPD, use the navigation in the upper left of the canvas. Parent topic:Subprocess types

93

Creating a user attribute definition You can associate unique capabilities or qualities with one or more users by creating user attribute definitions.

Before you begin To perform this task, you must be in the IBM® Process Designer desktop editor.

About this task This procedure triggers dynamic group creation, which can be time consuming. You can configure IBM Business Process Manager to deactivate these triggers. See Deactivating dynamic group updates. You can use defined attributes when you create teams that are based on a user attribute rule. For more information, see Deprecated: Defining Team rules. When a user creates a new user attribute definition in a process application, the new attribute may need to be added to one or both of the following whitelists that describe authorization on a per-user-attribute level depending on the authorization requirement using a REST API for the specific attribute. These whitelists are included in the 00static.xml file and can be overwritten by users in the 100custom.xml file. - server/user-attributes/rest-authorization/public-attribute - server/user-attributes/rest-authorization/self-managable-attribute When accessed using a REST API, users that are not assigned privileges in the ACTION_MANAGE_ANY_USERATTRIBUTE action policy: - Can only see attributes of themselves and other users listed as public-attribute - Can only see and update own attributes listed as self-managable-attribute The following example shows how to add a new attribute to the list of selfmanagable attributes in the 100Custom.xml file. CustomAttribute

To create a user attribute definition:

Procedure 1. Open the Process Designer desktop editor. 2. Open a process application in the Designer view. 3. Click the plus sign next to Data and select User Attribute Definition from the list of components. 4. In the New User Attribute Definition window, provide a unique name for the attribute, and click Finish.

94

5. Supply the following requested information about the user attribute definition: Table 1. Input required for the user attribute definition Dialog area Common

Field or link Name Documentation

Type

Business Object

Obtain current value from...

Source

Obtain possible values from...

Source

If you select Any Allowed... If you select List...

Description Displays the name that you provided in step 2. (Optional) Provides a description of the attribute in this field. Specifies the business object type. The default type is String. Click Select to specify a different type. Click New if you want to define a new business object. Specifies the source of the current value. The source is IBM Business Process Manager. Specifies the sources of other possible values for the user attribute. Select the source from the list, Any Allowed, or List. The choice that you make determines the information that is required. Specifies that the possible values for the attribute are limited only by its business object type. Enter each possible value in the Value field and click Add. You can remove values from the list by clicking Remove or change the order of the values that are displayed by clicking Up and Down.

6. Click Save on the main toolbar.IBM Process Designer saves the user attribute definition, and you can use the attribute when creating teams. Parent topic:Creating a business process definition (BPD)

95

Validating processes Use validation functions to refine process definitions as you build them. The Designer in Process Designer includes validation functions that alert you to issues in your process applications and toolkits. Validation provides feedback about the following types of issues: - Broken references, such as missing implementations for activities - Problems with parameter mappings - Duplicate names and other naming violations If IBM® Business Process Manager Designer detects issues, the Validation errors category in the library displays the number of errors detected. You can click the category to display a list of issues. Double-click an item in the list to open the item, and then click the Validation Errors tab to list each error for the selected item. Parent topic:Creating a business process definition (BPD)

96

Task types Learn more about the task types that are available when modeling with IBM® Process Designer. IBM BPM supports the following task types: Table 1. Available task types Task type User Task

Description User tasks must be completed by process participants and are associated with Human services by default. When you drag a Human service from the library to a BPD diagram, Process Designer automatically creates an activity with a User task with the Human service selected. When you drag an activity from the palette to a participant lane in a BPD diagram, Process Designer automatically creates an activity with a User task with the Default Human service selected. For cases where you want a user to start the service but no additional user involvement is required, you can also choose a user task type and associate a service with it, such as an Integration or Advanced Integration service. In this way, Process Designer automatically creates the required user implementation that you need when you drag process components onto a diagram. You can also choose User Task and an associated service for an activity implementation, as described in Implementing activities in a BPD.

97

System Task

Script Decision Task

System tasks must be completed by an automated system or service and are automatically run without a need for user initiation regardless of the type of lane in which they are defined in a BPD diagram. When you drag an Ajax service, General System service, Integration service, or Advanced Integration service from the library to a BPD diagram, Process Designer automatically creates an activity with a System task type, regardless of whether the service is dragged to a system lane or to a participant lane. Dragging an activity from the palette to a system lane in a BPD diagram automatically creates an activity with a System task with the Default System service selected. System tasks that you place in a non-system lane are also run by the system. In this way, Process Designer automatically creates the System implementation that you need when you drag process components onto a diagram. You can also choose System Task and an associated service for an activity implementation, as described in Implementing activities in a BPD. A script uses JavaScript to access and manipulate data. Decision tasks are useful when you want a decision or condition in a business rule to determine which process implementation is started. When you drag a Decision service from the library to a BPD diagram, Process Designer automatically creates an activity with a Decision task. You can also choose Decision Task and an associated Decision service for an activity implementation, as described in Implementing activities in a BPD.Note: Decision tasks in IBM BPM are equivalent to BPMN 2.0 Business Rule Tasks.

Note: Simple and multi-instance loop properties can be defined for all task types. For more information, see Creating loops for a BPD activity. Parent topic:Creating a business process definition (BPD)

98

99

Creating user interfaces for a BPD Create customized user interfaces that a user sees for the process instance in Process Portal.

About this task IBM® Business Process Manager provides a user interface for your instances in Process Portal. You can either use the provided interface or you can create your own user interface and make it the default user interface for all users. Optionally, you can also create your own user interface that is customized for instance owners. Attention: A process instance user interface must be implemented as a client-side human service. You cannot implement it as a heritage human service. These are the process instance user interfaces that you can create: - The Default user interface that overrides the user interface that is provided by IBM BPM. Any user that has permission to see the process instance in Process Portal will see this interface. You can create a client-side human service and specify it as the user interface. If you do not specify a client-side human service here, the user interface that is provided by IBM BPM is used. - The Instance Owners user interface is an optional user interface that you can create for the team that is specified in the Instance owner team field in the Overview page. You can create a client-side human service and specify it as the user interface for the instance owners.

Procedure To create a process instance user interface, first create a client-side human service, then create your customized interface by modifying the generated service and adding a coach. 1. Open the BPD for which you want to create the user interface. 2. Switch to the Views page. 3. Under Details UI, select the interface that you want to create (Default or Instance Owners). 4. Select a client-side human service, or create a new one. IBM BPM provides a template in the Dashboards toolkit, called Instance Details UI Services Template. You can copy this template and modify it to create your custom UI. The template contains the following coaches: - View Instance Details coach, which contains the following coach controls: - Default Instance Details Template - displays the instance details in Process Portal - Data section - displays the values of the variables that are passed into the client-side human service. - Show error, which returns an error if the instance is not found. For more information, see Instance Details UI Service template.

100

5. Map the process variables to the client-side human service variables. To automatically map input properties with process variables, click the auto-map icon . 6. Open the client-side human service, and click Run to test the client-side human service and the coach.Note: If you copied the template in step 4, remove the defensive logic that shows an error when the instance ID is null. 7. To test the interaction between the user interface and the process: A. Open the BPD and click Run Process in the toolbar. B. Switch to the Inspector when prompted. C. In the Inspector, select the process instance and click the Runs the Details UI for the selected BPD Instance in the toolbar. Process Portal opens in your default browser showing the process instance user interface. You can view the user interface, enter data, and interact with the process. Parent topic:Creating a business process definition (BPD)

101

Building services Use services to implement the activities in a business process definition (BPD). When a BPD starts and the tasks within it are invoked, services perform the required functions. The type of service that you choose to create depends upon the requirements of the activity. For example, if an activity requires integration with an external system, such as a database, you can create an integration service. If an activity requires that call center personnel enter data about customer requests, you can create a human service with a coach. - Service types Learn about the types of services available in IBM BPM and when to use each type. - Service components Learn about the tools and components available when building services in IBM Process Designer. - Building a Decision service Build a Decision service when you want a decision or condition in a business rule to determine which process implementation is invoked. For example, when a certain condition evaluates to true, Process Designer implements the associated activity or action. - Building a client-side human service Build a client-side human service to handle the interaction for process or case instances between the system and users through interactive tasks, dashboards, or user interfaces. Within a client-side human service, you can use coaches, clientside scripts, and services to create a service flow that is run entirely in a web browser.Case management functions are only available if you have IBM BPM Advanced with the Basic Case Management feature installed. - Building a heritage human service Build a heritage human service when you want an activity in your business process definition (BPD) to create an interactive task that process participants can perform in a web-based user interface. - Building an Ajax service Build an Ajax service when you want a coach view to send data to or retrieve data from the server asynchronously, such as for auto-completion in text fields, for default selection values in selection lists, and so forth. - Building an integration service Build an integration service when you want a flow to interact with an external system. - Building an advanced integration service An advanced integration service is used to call a service implemented in IBM Integration Designer from a business process definition (BPD) (via a system task) or another service (via a nested service). - Building a General System service Use General System services when you want to orchestrate other background services, manipulate variable data, generate HTML for a Coach, or perform some

102

other actions that do not require any integrations or business rules. Parent topic:Modeling processes

103

Service types Learn about the types of services available in IBM® BPM and when to use each type. The type of service that you choose to create depends upon the requirements of the activity. For example, if an activity requires integration with an external system, such as a database, you can create an integration service. If an activity requires that call center personnel enter data about customer requests, you can create a client-side human service with a coach. The following table describes the types of services available in IBM BPM: Table 1. Types of services available in IBM BPM Service type Heritage human service

Description Use a heritage human service to implement an interactive task in a business process definition (BPD) or a dashboard that users can use in a webbased application such as IBM Process Portal. Heritage human services run on the server and supply user interfaces to a web browser. Heritage human services are authored in the Process Designer desktop editor, and can contain coaches, heritage coaches, and postpones. A heritage human service is the only type of service that can call other heritage human services.

104

See... Building a heritage human serviceDifference between client-side human services and heritage human services

Client-side human service Use a client-side human Building a client-side service to implement an human service interactive task, a dashboard, or a user interface for a case or process instance that users can use to manage cases or processes in an application such as IBM Process Portal. Client-side human services run within a web browser and can call the server for data when needed. Client-side human services are authored in the Process Designer web editor, and can contain coaches, client-side scripts, services, and events. Client-side human services cannot use heritage coaches. Ajax service Use an Ajax service when Building an Ajax service you want to include a control in a coach to implement dynamic data selection such as automatically populating drop-down lists and automatically completing edit boxes. An Ajax service can pull data dynamically from a connected data source, such as a database. You cannot call an Ajax service from other types of services, but an Ajax service can call other nested services.

105

Decision service

Integration service

Advanced integration service

IBM Case Manager integration service

Use a decision service when you want a condition to determine the implementation invoked. For example, when a certain condition evaluates to true, IBM BPM implements the JavaScript expression that you provide. Decision services cannot include Java™ or Web Service integrations directly. You can call a decision service from any other type of service and a decision service can call other nested services. Use an integration service when you want to integrate with an external system. An integration service is the only type of service that can contain a Java or Web Service integration. You can call an integration service from any other type of service and an Integration service can call other nested services. Use an advanced integration service when you want to integrate with a service created in IBM Integration Designer. Use an IBM Case Manager integration service when you want to integrate with an IBM Case Manager server

106

Building a Decision service

Building an Integration service

Building an Advanced Integration service

Integrating BPDs with IBM Case Manager cases

General system service

Use a general system Building a General System service when you need to service coordinate other nested services or you need to manipulate variable data. For example, if you need to implement data transformations or generate HTML for a coach, you can use a general system service. General system services cannot include Java or Web Service integrations directly. You can call a general system service from any other type of service and a general system service can call other nested services.

Parent topic:Building services Related information: Examples of building services with heritage coaches

107

Service components Learn about the tools and components available when building services in IBM® Process Designer. When developing a service diagram in the Designer view in IBM Process Designer, the following tools and components are available from the palette. Not all tools and components are available for each type of service. - All service types - Integration service - Heritage human service - Decision service - IBM Case Manager Integration service

All service types The following tools and components are available from the palette for all service types:Table 1. Tools and components available from the palette for all service types Component icon

Description Enables you to select and move components on the diagram. Enables you to connect service components to establish the order in which the steps in the service occur. Use when you want to write JavaScript to run on the Process Server in the service context. The Server Script component is useful for parsing through variables and executing programmatic commands. Use to bind blocks of formatted text (for example, HTML, XML, or XSLT) directly to a service variable. This eliminates the need to store large blocks of text in default values for variables. Use to model a point in the process execution where only one of several paths can be followed, depending on a condition. Use to end service execution. For services that contain multiple paths, each path requires its own end event. Note: An end event is automatically included each time you create a service. Use to add information about the overall service or each step in the service to the diagram. Adding notes helps other developers understand your design.

108

Use to purposely throw an error and end processing. You might, for example, use an Error End Event component if you return too many rows from a database (over a limit that is normal and would bog down the server). Use to invoke an undercover agent (UCA) from your service. Use to listen for errors from the service component to which it is attached. Use to indicate a point in a service at which you want IBM Business Process Manager to capture the runtime data for reporting purposes. For more information about tracking data, see Enabling processes for tracking and reporting. Use to incorporate other services in your current service. Nested services are generally defined to perform specific, repeatable functions such as exception handling routines, integration with outside systems, or data manipulation. Nested services are often used in multiple process applications and likely reside in a toolkit. Note: Human and Ajax services cannot be nested. Note: You must use a nested service to invoke an Advanced Integration service. Use to send task-related alerts (deprecated). In prior releases, the Send Alert component was used to send alerts to an IBM Process Portal user. Starting in IBM Business Process Manager V8, alerts can be retrieved only with the TWSearch JavaScript API by querying on tasks with the status of Alert.

Integration service The following tools and components are available from the palette for Integration services only:Table 2. Tools and components available from the palette for Integration services only Component icon

Description Use to run an external web service. This component enables you to supply a WSDL URI and then use any of the available services.

109

Use to call methods from a Java class. You can use the methods to complete tasks like reading or writing files or sending SMTP mail. Use to integrate with an IBM Enterprise Content Management system.

Heritage human service The following tools and components are available from the palette for heritage human services.Table 3. Tools and components available from the palette for heritage human services Component icon

Description Use to implement the interfaces for your heritage human services so that users can participate in a business process. For more information, see Building coaches. The coach tool is shared with the client-side human services. For more information, see Tools available from the palette for client-side human services. Use to implement the interfaces for your heritage human services so that users can participate in a business process. For more information, see Building heritage coaches. This component is used for heritage human services only. Use to change the priority, due date, status, or other aspects of a task. Use to halt processing without changing the status of a task. This component is used for heritage human services only.

Decision service The following tools and components are available from the palette for Decision services only:Table 4. Tools and components available from the palette for Decision services only Component icon

Description Use to build conditions for your Decision services. Use to include decision services available on an ILOG JRules Rule Execution Server.

110

Use the Business Action Language (BAL) Rule component to author business rules using natural language technology

IBM Case Manager Integration service The following tools and components are available from the palette for IBM Case Manager services only:Table 5. Tools and components available from the palette for IBM Case Manager services only Component icon

Description Use to integrate a case management case in IBM Case Manager.

Parent topic:Building services Related information: Tools available from the palette for client-side human services

111

Building a Decision service Build a Decision service when you want a decision or condition in a business rule to determine which process implementation is invoked. For example, when a certain condition evaluates to true, Process Designer implements the associated activity or action. IBM® Process Designer supports business rule authoring tasks as performed by business analysts and business users who are rule designers rather than programmers. Business rule designers can express business logic using rule syntax that resembles natural human language. This rule syntax is called Business Action Language (BAL), which is a declarative language that relates business concepts to business data and actions. Business rules are an expression of business policy in a form that is understandable to business users and that can be run by a rule engine. Business rules formalize a business policy into a series of "if-then" statements. In Process Designer, business rules are included in a business process definition (BPD) by adding a Decision service to the process. Add a Decision service to a Process Application when the actions that should take place in your process depend upon one or more conditions. For example, if an employee holds the position of Director and submits a meal expense for more than $250, then you can create a rule and set a variable in the rule, such as approvalRequired, to route the process sequence flow into a specific approval activity. A Decision service contains one or more components. There are three types of components: - BAL Rule - You can use the rule editor in this component to author business rules using Business Action Language (BAL), a natural language technology. - JRules Decision Service - IBM Business Process Manager integrates with IBM WebSphere ILOG JRules using the JRules Decision Service component. You can use this rule component to connect to and implement rule applications that are available on a JRules Rule Execution Server. - Decision Table - The Decision Table component contains a rule table. Each row in the rule table represents a Boolean condition that evaluates to true or false at run time. When a rule evaluates to true, the JavaScript expression that you provide as the rule action is started. When building a Decision service, follow these guidelines: - Build your rule hierarchy so that rule conditions are ordered from most complex to least complex. - Create a final condition that is a catch-all rule. This rule is necessary if you cannot guarantee that the variable that you want to modify in the rule will be set before running the process that triggers the Decision service. - Consider encapsulating your rules in a single-function Decision service, which allows the service to be available to any other part of the process application that needs the same rule logic.

112

The following topics describe how to author, implement and manage business rules in Process Designer. - Scenario: Creating a Decision service in a Personalized Notification process This scenario shows you how to create, configure and test Business Action Language (BAL) rules in a Decision service. The scenario presents a sample business process that is used by a bank to notify a customer when a payment is made from a specific account. - Adding a Decision service to a process You can add a Decision service to a business process definition (BPD). Use a Decision service when you want a decision or condition to determine which process implementation is invoked. For example, when a certain condition evaluates to true, IBM Process Designer implements the associated activity or action. - Implementing an activity using a Decision service You can implement an activity using a Decision service. - Attaching a Decision service to a decision gateway You can use a decision gateway in your business process definition (BPD) when you need to model a point in the process execution where only one of several paths can be followed, depending on a condition. You can also attach a Decision service to a decision gateway. - Adding a BAL Rule component to a service The Business Action Language (BAL) Rule component provides a rule editor that allows rule designers to author business rules using natural language technology. Using natural language, instead of JavaScript, to author rules means that no programming expertise is required to create business rules, and the rules are easier for people to read and understand. - Adding and modifying Decision service variables Each IBM Business Process Manager Decision service has a set of input, output, and private variables that are declared for that service. The business terms and phrases that you define as variables are available for you to use when you are writing rules. For example, the variable appear in the Content Assist menu in the rule editor. - Testing a Decision service When you have finished creating a Decision service and authoring rules in a rule component, such as a BAL Rule component, you can test the Decision service to determine if the rules are being applied as you intended. If an error or exception occurs within a rule, you will see messages about the error during testing, and you can debug the specific rule component or rule that caused the error. - Scenario: Exporting rules to a Rule Execution Server This scenario shows you how to export, migrate and connect BAL rules to a rule execution server (RES). You can migrate the rules that you created in Process Designer to a business rules management system (BRMS) such as IBM WebSphere® ILOG® JRules, and then continue to use the rules in a business process definition. - Exporting rules for use in Rule Studio You can export a set of rules to create a project file that you can then import and 113

work on in IBM WebSphere ILOG JRules Rule Studio. - Adding a JRules Decision Service component to a service When building a Decision service in Process Designer, you can include decision services available on an ILOG JRules Rule Execution Server in your implementation. - Adding a Decision Table component to a service You can add a Decision Table component to a service. - BAL reference A reference guide to the Business Action Language (BAL), which is used to author rules in IBM Business Process Manager, is available in the IBM WebSphere ILOG JRules InfoCenter. - Decision service limitations Some functions and variables are not supported in a Decision service. Parent topic:Building services

114

Scenario: Creating a Decision service in a Personalized Notification process This scenario shows you how to create, configure and test Business Action Language (BAL) rules in a Decision service. The scenario presents a sample business process that is used by a bank to notify a customer when a payment is made from a specific account.

Before you begin To perform this task, you must be in the IBM® Process Designer desktop editor.

About this task This scenario assumes that there is an existing business process definition called Personalized Notification that includes a decision gateway named Send Alert. The process includes a Decision service with BAL rules to decide whether a notification is sent to the customer. The Decision service defines the conditions that must evaluate to true in order for the notification step to be triggered. Using the following steps, you can attach the NotificationRulesService to the Send Alert decision gateway. The rules in the Decision service control whether the sequence flow coming out of the gateway follows the "No notification" decision path, or the "Send notification" decision path.

Procedure To add a Decision service to the Personalized Notification process, complete these steps: 1. Open the Process Designer desktop editor. 2. Open a process application that contains a business process definition (BPD). 3. Create a new Decision service called NotificationRulesService. A. In the Library panel on the left side of the Process Designer window, move the mouse cursor over the Decisions item in the list of library items for the process application. B. Click the plus sign next to Decisions to add a new Decision service. C. In the Create New window, click Decision Service. D. In the New Decision Service window, enter NotificationRulesService as the Decision service name, then click Finish.

115

You can find more information about adding a Decision service in the related topic "Adding a Decision service to a process." 4. Add a BAL Rule component called AlertRules to the NotificationRulesService Decision service. A. Make sure that you are editing the NotificationRulesService Decision service. B. Click BAL Rule in the component palette and drag the BAL Rule component icon from the palette to the service diagram. C. In the Properties tab, enter AlertRules ad the name for the new BAL Rule component. D. Click Save, or use the Ctrl+S keyboard shortcut to save the Decision service.

You can find more information about adding a BAL rule component in the related topic "Adding a BAL Rule component to a service." 5. Create a business object called CheckingAccount that contains parameters such as CustomerName, Balance and Payments. A. Add a business object from the Process Designer library panel. 1. Click the indicator next to the process application name in the library panel to see the categories of library items in the current process application. 2. Click the plus sign next to the Data library item. 3. In the Create New window, click Business Object. 4. In the New Business Object window, enter CheckingAccount as the name for the business object, then click Finish. B. In the Behavior section of the Business Object panel, select Complex Structure Type as the Definition Type. C. Add parameters to the CheckingAccount business object. 1. In the Parameters section of the Business Object panel, click Add. 2. In the Parameter Properties section, add the CustomerName parameter with the variable type set to String, the Balance parameter with the variable type set to Decimal, and the PastPayment parameter with the variable type set to Payment. D. Click Save, or use the Ctrl+S keyboard shortcut to save the Decision service.

116

You can find more information about creating a business object in the related topic "Adding variable types and business objects to a Decision service." 6. Define which of the parameters are used as input variables to the Decision service, such as CustomerName, Balance and PastPayment, and which parameters are output variables from the Decision service, including the notification message. A. Make sure you are editing the NotificationRulesService Decision service. B. Click the Variables tab. C. Click Add Input to add the input variables: 1. In the Details section, enter accountIn as the name for the input variable. 2. Click Select next to Variable type and click CheckingAccount in the list. 3. Click the plus sign next to accountIn in the Variables list to confirm that CustomerName, Balance and PastPayment are included in the list. D. Click Add Output to add the output variable, notificationOut. 1. In the Details section, enter notificationOut as the name for the output variable. 2. Click Select next to Variable type and click Notification in the list. 3. Click the plus sign next to notificationOut in the Variables list to confirm that message is included in the list. E. Click Save, or use the Ctrl+S keyboard shortcut to save the Decision service.

117

You can find more information about defining Decision service variables in the related topic "Adding and modifying Decision service variables." 7. Use the BAL Rule editor to create rules in the AlertRules BAL Rule component. A. Make sure you are editing the NotificationRulesService Decision service. B. Click the Diagram tab, then click to select the AlertRules BAL Rule component. C. Click the Decisions tab. By default, the rule editor opens with an empty BAL rule window. The rule window contains a basic template for a simple rule, with one condition (if) and one action (then). D. Click inside the rule window to begin creating a new rule from the template. 1. Click the condition placeholder, next to if, to use the Content Assist menu to complete the condition. Add the following condition statements by doubleclicking on each as it appears in the list. If the list closes before you can select a condition statement, press Shift+Spacebar to reopen the Content Assist menu. - if the amount of - paymentIn - is more than - the balance of - accountIn The first part of the rule (if) looks like this:if the amount of paymentIn is more than the balance of accountIn

E. Click the action placeholder next to then and add the following condition statements. - set the message of - notificationOut - to - string When you double-click to select string, the edit cursor appears between two double quotation marks. Type the notification message, Payment takes account overdrawn between the double quotation marks.The second part of 118

the rule (then) looks like this:then

set the message of notificationOut to

"Payment takes account overdrawn";

F. Add a second rule editor window. Click the plus sign in the upper right corner of the BAL rule editor panel. Repeat the previous sequence of steps to create a second rule that looks like this:if there is no payment in the past payments of accountIn where the payee of this payment is the payee of paymentIn , then set the message of notificationOut to the message of notificationOut + "\n" + "Payment to new payee: " + the payee of paymentIn ;

G. Click Save, or use the Ctrl+S keyboard shortcut to save the Decision service.

You can find more information about using the BAL Rule editor in the related topic "Creating a rule using the rule editor." 8. Attach the NotificationRulesService Decision service to the Send Alert decision gateway. A. Make sure you are editing the NotificationRulesService Decision service. B. In the business process definition diagram, click the Send Alert decision gateway icon to select the decision gateway. C. Click the Properties tab. D. Click Decision. E. In the Decision Service section, click Select. Click to select the NotificationRulesService Decision service. F. Click Implementation in the Properties tab. G. Under the Decisions heading, add a variable statement to each decision to control the output of the decision gateway.

You can find more information about decisions in the implementation of a gateway, and attaching a Decision service to a gateway, in the related topic "Attaching a Decision service to a decision gateway." 9. Test the Decision service and the BAL rules that you created and attached to the decision gateway. 119

A. Make sure that you are editing the NotificationRulesService Decision service and the AlertRules BAL Rule component. B. In the NotificationRulesService Decision service, click to select the Send Alert decision gateway. C. Set a breakpoint for the gateway. Set breakpoints at specific locations in the process where you want the process flow to pause during testing so that you can determine the status of the process, and identify any errors that might have occurred. D. In the AlertRules BAL Rule component panel, click the Debug icon in the banner above the rule editor windows.

E. The IBM BPM Debug Service opens in a new browser window. F. When Process Designer prompts you to change to the Inspector interface, click Yes. The prompt to switch to the Inspector perspective might be covered up by the Debug window. G. Click Step in the Debug window to run the Decision service one step at a time. The Inspector clearly identifies any errors in the Execution State panel. The Inspector also tells you where the error happened, and links directly to the source of the problem. The Debug service browser window captures error and exception messages. For more information about using the Debug service and the Inspector window to identify and fix Decision service problems, refer to the related topic "Debugging a Decision service." H. If you make any changes to resolve errors in the Decision service or the BAL rules, click Save, or use the Ctrl+S keyboard shortcut to save the Decision service.

What to do next When you have finished creating, configuring and testing the AlertRules BAL rules in the NotificationRulesService Decision service, then you have completed the scenario procedures. If you want to refine or share the rules that you create in Process Designer, you can export the rules into a project file and import them into IBM WebSphere ILOG JRules. For more information, refer to the related topic "Exporting, migrating and connecting BAL rules to a rule server." Parent topic:Building a Decision service Related information: Adding a Decision service to a process Adding a BAL Rule component to a service Adding variable types and business objects to a Decision service Adding and modifying Decision service variables 120

Creating rules using the rule editor Attaching a Decision service to a decision gateway Debugging a Decision service Scenario: Exporting rules to a Rule Execution Server

121

Adding a Decision service to a process You can add a Decision service to a business process definition (BPD). Use a Decision service when you want a decision or condition to determine which process implementation is invoked. For example, when a certain condition evaluates to true, IBM® Process Designer implements the associated activity or action.

Before you begin To perform this task, you must be in the IBM Process Designer desktop editor. To create services, you must have access to a process application or toolkit in the Process Center repository. Access to process applications and toolkits is controlled by users who have administrative rights to the repository. For more information, see Managing access to the Process Center repository.

Procedure 1. Open the Process Designer desktop editor. 2. Open a process application that contains a BPD. 3. Create a new Decision service. A. Click the plus sign next to Decisions to add a new Decision service. B. In the Create New window, click Decision Service. C. In the New Decision Service window, enter a name for the new Decision service, then click Finish. D. Process Designer displays the diagram of the service with the default Start Event and End Event components. 4. Drag a rule component, such as a BAL Rule, JRules Decision Service or Decision Table component, from the component palette to the Decision service diagram. 5. Depending on which component or components you added to the service diagram, follow the additional steps in the following related topics to configure the components in the Decision service: - Adding a BAL Rule component to a service - Adding a JRules Decision Service component to a service - Adding a Decision Table component to a service

What to do next You can now nest this Decision service in any other service within your process application that requires this logic. Be sure to adjust the input and output variables as required for each implementation. See Declaring and passing variables for more information.

Parent topic:Building a Decision service Related information: Declaring and passing variables Adding a BAL Rule component to a service Adding a JRules Decision Service component to a service

122

Adding a Decision Table component to a service

123

Implementing an activity using a Decision service You can implement an activity using a Decision service.

Before you begin To perform this task, you must be in the IBM® Process Designer desktop editor.

Procedure To select a Decision service as the implementation for an activity, complete the following steps: 1. Open the Process Designer desktop editor. 2. Open a process application that contains a business process definition (BPD). 3. Open the BPD diagram that contains that activity that you want to implement using a Decision service. 4. Click the activity in the diagram to select the activity. 5. Click the Implementation option in the properties. 6. Click the drop-down list and select Decision Task from the available options. 7. Click the Select button to choose the Decision service that you want from the library. If the service does not yet exist, click the New button to create it. Parent topic:Building a Decision service

124

Attaching a Decision service to a decision gateway You can use a decision gateway in your business process definition (BPD) when you need to model a point in the process execution where only one of several paths can be followed, depending on a condition. You can also attach a Decision service to a decision gateway.

Before you begin To perform this task, you must be in the IBM® Process Designer desktop editor.

About this task When you attach a Decision service to a decision gateway, the process follows a specific sequence line coming out of the gateway based on the result of the conditions and actions in the rule components in the Decision service. If there are multiple decisions in the Implementation properties for the gateway, the decisions are evaluated from top to bottom and the path for the first decision that evaluates to true is followed. If no decisions evaluate to true, the default path is followed.

Procedure To attach a Decision service to a decision gateway, complete the following steps: 1. Open the Process Designer desktop editor. 2. Open a process application that contains a business process definition (BPD). 3. In the BPD diagram, click the decision gateway icon to select the decision gateway where you want to attach the Decision service. 4. Click the Properties tab. 5. Click Decision. 6. In the Decision Service section, click Select. 7. Select the Decision service you want to attach to the gateway from the list of available services. 8. If you decide not to use an existing Decision service, you can create a new service. Click New next to the Service field. You can remove an attached Decision service from a decision gateway. Click the delete icon (X) next to the Decision service name. 9. The Inputs section contains a variable condition statement field that controls the behavior of the gateway, based on the result of the rules in the rule component. A. To select an input variable statement, click the variable icon to display a list of available variables. B. The Inputs section includes an auto-map function. To create a mapping between the variables used in the Decision service and the variables that are used in the main business process definition, click the auto-map icon . When developing processes in IBM Business Process Manager, you must set the input and output mapping for each activity included in a business process definition so that the variable values received and generated by services map to the variables from the main process definition. For more information about the auto-map function, refer to the related topic "Mapping input and output data for an activity." 125

The text field under the Inputs heading shows the JavaScript object that represents the variable. The variable name is displayed to the right of the Inputs field. 10. Click Implementation in the Properties tab. 11. Under the Decisions heading, add a variable statement to each decision to control the output of the decision gateway. The last decision is the default condition sequence line, which is followed if none of the decisions evaluate to true. You can change the position of a decision. Click the down arrow or the up arrow next to a decision to move it down or up in the decision list. 12. For each decision above the last (default) decision, add an output variable statement. Click the variable icon to display a list of available output variables that are defined in the Decision service. The text field for each decision shows the JavaScript object that represents the variable condition. 13. To enable the process to process the decision and choose the correct output sequence line for the decision gateway, you must also specify a comparison function and a value for each decision. For example, if the purpose of the decision gateway is to determine whether a notification message is sent to a customer or not, then the decisions are No Notification (the process ends with no message sent), or Send Notification. The value of the No Notification decision is null, because the rules in the decision service have determined that no notification message is required. The value of the Send Notification decision is determined by variables that are defined in the rules. In this example, Send Notification is the default decision. The example decisions are illustrated in the

following figure: In this screen capture, the input variable tw.local.notification.message in the top position is set to no message as output; that is, no text will be sent as indicated by the quotation marks with no text inside (""). This output would be determined by the logic of the decision service. Under a certain set of conditions, no message would be sent. For example, if the decision service checked a database and found that the customer no longer existed it would not send a message. Another possibility might be that the customer had an invalid email address, so no message would be sent.The input variable and its output in the bottom position are hidden in this screen capture; however, by using the arrows you could move the bottom position up to the top position and the code would be displayed. This is the default output, which is to send a message. The message sent as output could be in quotation marks, for example, "Your order is confirmed," or the message sent as output might be in an another variable such as orderConfirmationNumber, which would contain the order number for something the customer had ordered. Parent topic:Building a Decision service Related information: Mapping input and output data for an activity or step 126

127

Adding a BAL Rule component to a service The Business Action Language (BAL) Rule component provides a rule editor that allows rule designers to author business rules using natural language technology. Using natural language, instead of JavaScript, to author rules means that no programming expertise is required to create business rules, and the rules are easier for people to read and understand.

About this task The following steps describe how to add a BAL Rule component to a sample Decision service. The purpose of the sample service is to determine whether approval is required for certain employee expenses. The sample service is a singlefunction Rule that can be called from any other service. Restriction: The following variable types cannot be used with BAL rules in Decision services: - ConditionalActivity - IndexedMap - Map - NameValuePair - Record - SLAViolationRecord - SQLDatabaseType - SQLParameter - SQLResult - SQLResultSetColumn - SQLResultSetRow - SQLStatement - TWHolidaySchedule - TWTimePeriod - TWTimeSchedule - TWWorkSchedule - TaskListData - TaskListItem - TaskListProperties - TaskListFilterProperties - TaskListSortBySelectionType - XMLDocument - XMLElement - XMLNodeList

Procedure 1. Open the process application in the Designer view. 2. Create a Decision service. 3. In the diagram of the new Decision service, click BAL Rule in the component palette and drag the BAL Rule component icon from the palette to the service

128

diagram. 4. In the Properties tab, enter a name for the new BAL Rule component, such as ExpenseApproval. 5. Click the Variables tab. 6. Click Add Private to add a private variable to the Decision service. For this sample Decision service, add the private variable, request. A. Replace Untitled1 in the Name field with request . B. Click Select next to Variable Type and select the type from the list. 7. If you use the Activity Wizard to create a Decision service, you can choose existing variables to add as input and output. You should use the Activity Wizard when you start with an existing activity and want to quickly create a service to implement the activity. To access the wizard, right-click an activity icon in a process diagram and select Activity Wizard from the list of options. 8. Click Add Private. 9. Replace Untitled1 in the Name field with approvalRequired . 10. Click Select next to Variable Type and select the Boolean type from the list. The Boolean variable type is included in the IBM® BPM System Data toolkit. The System Data toolkit is included in each process application by default. 11. Click the Decisions tab to open the rules editor.

What to do next Create a rule that is implemented for this Decision service. Refer to the related topic "Authoring rules using the BAL rule editor." - Creating rules using the rule editor You can create rules using the Business Action Language (BAL) rule editor. The rule editor uses natural language technology to express business decisions in a form that is readable by humans but can also be run by a rule service runtime such as the JRules Rule Execution Server. - Business rule parts and structure Business rules, such as action rules or decision tables, express business policy statements using a predefined business vocabulary that can be interpreted by a computer. Rules authored in the Business Action Language (BAL) are also easily readable by humans. - Defining variables in the rule editor Variables are defined in the definitions part of a business rule. - Copying and pasting content in the rule editor You can copy content from a rule to the system clipboard, or paste content written outside the rule editor into the editor window. - Setting the rule language You can use the locale preference setting provided in IBM Process Designer to set the language used in a BAL Rule component. - Troubleshooting BAL rule editor errors The Business Action Language (BAL) rule editor highlights errors with red underline in the editing window. Parent topic:Building a Decision service Related information: 129

Declaring variables for a BPD or a service in Process Designer

130

Creating rules using the rule editor You can create rules using the Business Action Language (BAL) rule editor. The rule editor uses natural language technology to express business decisions in a form that is readable by humans but can also be run by a rule service runtime such as the JRules Rule Execution Server.

About this task You can use the BAL rule editor to build rules, add rule parts, statements, and fragments, and replace placeholders with variables and values. Use the completion menu in the editor to insert or edit constants, values, parts, or fragments of rule statements. While you are creating or editing rules, the editor highlights errors to help you identify and resolve problems in your rules. A business rule consists of some or all of the following parts. The parts must be defined in the following order: 1. definitions part (optional) 2. if part 3. then part 4. else part (optional) For more information about the parts and structure of a business rule, refer to the related topic "Business rule parts and structure." The following steps describe how to author a rule using the rule editor. The rule is implemented in a BAL Rule component as part of a sample Decision service. The purpose of the sample service created in the procedure steps is to determine whether approval is required for certain employee expenses. The sample service is a single-function rule that can be called from any other service.

Procedure 1. Make sure you are working in the sample Decision service that was created in the related topic "Adding a BAL Rule component to a service." 2. Click the Decisions tab to open the rule editor. 3. By default, the rule editor opens with an empty BAL rule window. The rule window contains a basic template for a simple rule, with one condition (if) and one action ( then). 4. Click inside the rule window to begin creating a new rule from the template. A. Click the condition placeholder, next to if, to use the Content Assist menu to complete the condition. Double-click a condition statement in the menu to add that condition to the rule. - If the list of conditions is long, you can use the Tree Completer menu instead of the Content Assist menu to select the condition statement. With the edit cursor on the placeholder, press Ctrl+Shift+Spacebar to open the Tree Completer menu. - If you know the name of the condition you want to insert, start typing the condition name. The Tree Completer shows all the conditions that match the name as you type, as shown in the following diagram:

131

B. Click the action placeholder, next to then, to select from the menu of possible actions. Double-click an action statement in the menu to add that action to the rule. For more information about using the menu to select actions, refer to the related topic in the IBM WebSphere ILOG JRules InfoCenter, "Inserting a term or a phrase." 5. To add additional rule parts to the rule, click to place the editor cursor above or below the existing rule content, then press Ctrl+Spacebar to activate the Content Assist menu. The Content Assist box displays a list of valid rule parts. For example, to create a definition rule part, click before the if condition section, then press Ctrl+Spacebar to open the Content Assist menu and select definitions. To create an else rule part, click below the then section of the rule. 6. To add additional rules to the BAL Rule component, click the plus symbol at the top of the rule editor window. Each time you click the plus symbol, a rule editor window is opened. Each window contains the simple rule template. 7. In a BAL Rule component that contains multiple rules, you can change the order of the rules. Click the up arrow beside the editing window to move the rule up one place in the rule order. Click the down arrow to move the rule down one place in the rule order. 8. The rule editor saves the rules periodically as you are authoring. To save all the rules in the BAL Rule component while you are authoring, click Ctrl+S, or click the Save icon in the Process Designer action bar. 9. To exit the rule editor, click the exit icon (X) next to the Decision service name. Parent topic:Adding a BAL Rule component to a service Related information: Business rule parts and structure Adding a BAL Rule component to a service Inserting a term or a phrase

132

Business rule parts and structure Business rules, such as action rules or decision tables, express business policy statements using a predefined business vocabulary that can be interpreted by a computer. Rules authored in the Business Action Language (BAL) are also easily readable by humans. For example, the business policy "refuse a loan to customers whose credit score is below the minimum of 200" can be expressed as a business rule in the following way: - definitions

- set minimum_score to 200; - if

- the credit score of the borrower is less than minimum_score - then

- refuse the loan with the message "Credit score below" + minimum_score; The parts must be defined in the following order: 1. definitions part 2. if (conditions) part 3. then (actions) part 4. else (optional actions) part

Definitions The definitions part of a rule gives you more control over your business rules when you set variables at the beginning of your rule. Variables help you identify and then reference an occurrence of a business term by a convenient name. Use variables to make your business rules less ambiguous and easier to understand. Define a variable by giving it a name of your choice and then setting a value for the variable. This value can be a number (or an arithmetic expression whose result is a number), text, or a predefined business term that already exists in your rule (for example, customer). Once you have set a variable, it becomes available in all the parts of the current rule. The variable is valid only in the rule in which it is defined. The simplest use of definitions is to define a constant value that you can use throughout your rule. For example, by declaring a variable called minimum_score in the example rule, you make the rule easier to understand: - definitions

- set minimum_score to 200; This is a very basic illustration of the definitions part of a rule. For more information about complex versions of the definition part, such as multiple occurrences of a value, or adding a where clause to a definition to apply further restrictions on the variables, refer to the related section in the WebSphere ILOG JRules InfoCenter, "Understanding your rules -- Definitions." A related link is provided.

Conditions The condition part of a rule specifies under what conditions the actions in the action part of the rule will be carried out. Conditions are represented in the rule editor by

133

the text (or number) that appears after if, ending at then. The word then signals the beginning of the action part of the rule.In the example rule, the condition is defined so that when the credit score of the borrower is below the minimum value, then the loan to the customer is refused. - if

- the credit score of the borrower is less than minimum_score This is a simple condition that is either true or false. The action is carried out if this condition is true. The condition part of a rule can be made up of one or more condition statements. For more information about conditions, refer to the section "Understanding your rules -- Conditions" in the WebSphere ILOG JRules InfoCenter.

Actions The action part of a rule describes what to do when the conditions of the rule are met. Actions are represented in the rule editor by the text that appears after then and else. If there is more than one action to perform, the actions are carried out in the order that they appear in the action part of the rule.In the example rule, the action is defined so that when the condition evaluates to true, then the resulting action is to refuse the loan, and issue a message "Credit score below 200." - then

- refuse the loan with the message "Credit score below" + minimum_score; Optionally, you can include an else part in a rule. The else part of a rule is an optional block of actions that specify what to do when the conditions are not met. You can use an else rule part in combination with variables in the definitions part to control the rule action more precisely. If a rule contains both definitions and a condition part, the else part of a rule will only be run if the conditions set in the variables are satisfied and the condition part of the rule is not satisfied. This sample rule shows this application for the else part: - definitions

- set applicant to a customer; where the category of this customer is Gold; - if

- the value of the shopping cart is more than $100 - then

- apply a 15% discount - else

- apply a 5% discount; This rule applies an extra discount only for customers who qualify for the Gold category. For more information about actions, refer to the section "Understanding your rules -- Actions" in the WebSphere ILOG JRules InfoCenter.

Parent topic:Adding a BAL Rule component to a service Related information: Understanding your rules: Definitions Understanding your rules: Conditions Understanding your rules: Actions 134

135

Defining variables in the rule editor Variables are defined in the definitions part of a business rule.

Before you begin Variables are accessible from business rules when you add them to the rule vocabulary. For more information about verbalizing variables, refer to the related topic "Adding and modifying Decision service variables."

About this task You can use a variable to identify and then refer to an occurrence of something by a convenient name. Use variables to make your business rules clear and easy to understand. When you create a variable in a rule, the variable is only valid for that rule, although the variable can be used in a all parts of the rule. Variable names must be unique within a rule.

Procedure To define a variable, complete these steps: 1. In the definitions part of the rule, press Ctrl+Spacebar, and double-click to select set from the Content Assist menu. The content of the Content Assist menu changes to show the default name for new variables, variable1. After the definitions are specified, the Content Assist menu changes to show the closing semicolon. 2. Double-click in the Content Assist menu to insert the placeholder variable name variable1 in the rule. 3. Type over the placeholder variable name to replace variable1 with the name of your variable. If your variable is only one word, quotation marks are not required. If your variable is a phrase containing more than one word, you must put the phrase between quotation marks. 4. Press Ctrl+Spacebar, and select a variable type from the menu. In IBM BPM, every variable name is associated with a variable type, which determines what values are legal for the associated variable. For more information, refer to the related topic "Variable types." 5. After the variable type is specified, the Content Assist menu changes to show the closing semicolon, or the optional building blocks from, in, and where. If you have finished defining the variable, select the closing semicolon. To define a variable using the optional building blocks, continue by selecting from, in, or where. 6. The variable definition ends with the closing semicolon. Once a variable is defined, you can use the variable in all parts of the business rule.

Example To make a rule easier to read, you can use a variable to define a one-to-one relationship between business objects. In the following business rule, the variable the shopping cart is defined using the one-to-one relationship between two objects: the ShoppingCart and the Customer: - definitions

136

-

set customer to a customer; set the cart to the shopping cart of customer;

- if

- the value of the cart is less than $100 - then

- apply 10% discount;

What to do next You must initialize complex variable structures before running the Decision service. In IBM® BPM, all complex variables and all lists (arrays) must be initialized before you use them in a BPD or service. If you do not initialize a complex variable or list, you may receive runtime errors or notice that the controls to which the variables are bound do not behave as expected. For more information, refer to the related topic, "Initializing complex variables and lists."

Parent topic:Adding a BAL Rule component to a service Related information: Variable types

137

Copying and pasting content in the rule editor You can copy content from a rule to the system clipboard, or paste content written outside the rule editor into the editor window.

Procedure To cut or paste content in the rule editor, complete the following steps: 1. You can copy the contents of an individual rule to the system clipboard. A. Click to place the edit cursor inside the rule that contains the rule content you want to copy. B. Highlight the content you want to copy. To select the entire content of the rule, press Ctrl+A. C. Copy the content to the clipboard using a keyboard shortcut, or the product menu, or the right-click menu, as described in the following steps: 1. Press the copy keyboard shortcut for your system. For example, on a Microsoft Windows system, the copy function shortcut is Ctrl+C. 2. From the main product menu, click Edit > Copy. 3. Right-click in the rule editor window and select Copy from the menu. 2. To paste content from the system clipboard into a rule, complete these steps. A. Make sure that the content you want to paste into the rule has been copied into your system clipboard. B. Click to place the edit cursor inside the rule in the location where you want the pasted content to appear. C. Paste the content to the rule editor window using a keyboard shortcut, or the product menu, or the right-click menu, as described in the following steps: 1. Press the paste keyboard shortcut for your system. For example, on a Microsoft Windows system, the paste function shortcut is Ctrl+V. 2. From the main product menu, click Edit > Paste. 3. Right-click in the rule editor window and select Paste from the menu. Parent topic:Adding a BAL Rule component to a service

138

Setting the rule language You can use the locale preference setting provided in IBM® Process Designer to set the language used in a BAL Rule component.

About this task The BAL Rule component language is set to English by default, but you can change the locale setting to change the language used in new BAL Rule components. Once the locale is set, you can create new BAL Rule components using the updated locale. However, if you add new rules to an existing BAL Rule component that was created before you changed the locale, the added rules use the locale setting from the BAL Rule component, not the updated locale preference setting.

Procedure To change the locale setting, complete the following steps: 1. From the main menu, click File > Preferences 2. Click IBM BPM to display the available options. 3. Click Rules. 4. Click English next to BAL Decision Locale, then select a language from the menu. Parent topic:Adding a BAL Rule component to a service

139

Troubleshooting BAL rule editor errors The Business Action Language (BAL) rule editor highlights errors with red underline in the editing window. To identify and correct an error in a rule, use the mouse to hover over the highlighted error in the editor. When the error tip window is displayed, click the underlined text in the error to go to the location of the error. Type in the editing window to correct the error.

Error indicators in the rule editor Errors in the rule editor are indicated by a wavy line under the section of the rule that is invalid. Errors are underlined in red. Warnings are underlined in yellow.

Using Quick Fix to identify and fix errors The Eclipse Quick Fix feature is available in the BAL rule editor. Quick Fix messages offer suggestions to help you correct rule errors. To see a proposed Quick Fix, click the light bulb icon next to the error indicator in the rule editor window, or place your cursor on the error and press Ctrl+1.The messages provide a list of possible corrections from which you can select the appropriate fix. To auto-correct an error from the quick fix message: 1. Put your cursor on the error indicator to display the error messages.

2. Click the light bulb icon or move your cursor to the error in the rule, and press Ctrl+1 to open the Quick Fix message.

3. From the list of suggestions, click to select the appropriate fix.

Parent topic:Adding a BAL Rule component to a service 140

141

Adding and modifying Decision service variables Each IBM® Business Process Manager Decision service has a set of input, output, and private variables that are declared for that service. The business terms and phrases that you define as variables are available for you to use when you are writing rules. For example, the variable appear in the Content Assist menu in the rule editor.

Before you begin To perform this task, you must be in the IBM Process Designer desktop editor.

About this task A Decision service might require input or output variables, or both. A service can also include private variables for processing that occurs only within the service. For more information about variables in a Decision service, refer to the related topic "Declaring variables for a service."

Procedure To add or modify variables for a Decision service, complete the following steps: 1. Open the Process Designer desktop editor. 2. Open a process application that contains a business process definition (BPD) in the Designer view. 3. Make sure you have selected the Decision service where you want to add or modify variables. 4. Click the Variables tab. 5. Existing variables are organized into three sections: Input, Output, and Private, as shown in the following example. Click the plus sign next to a section to see the variables in that section.

142

6. You can add a variable to the Decision service by completing one of the following steps: - Click Add Input to add a variable that you can use for input into a rule. - Click Add Output to add a variable that you can use for output from the rule. - Click Add Private to add a variable that applied only to the current Decision service. The following information applies to variables: - Variables are mapped to the IN, OUT or IN-OUT parameter directions automatically, depending on how the variable is used in the rule. For example, a variable that is referenced in a rule but is not updated at run time is identified as an IN variable. For more information about parameters, refer to the related topic "Adding variable types and business objects to a Decision service." - The input or output designation for variables might affect the way the Decision service runs, but the designation is not significant when you are authoring BAL rules because input, output and private variables are all referenced identically in a BAL rule. - If you create an input and an output variable that have the same name, only one variable is actually created. The variable is used for both input and output at the Decision service level. - Exposed Process Variables (EPVs) are managed at the process application level, and allow the IBM Business Process Manager administrator to specify designated users who can set or alter variable values using the Process Admin Console while instances of a process are running. The Decision service can pick up an EPV variable that has been created in a process application and use the variable in a rule to affect the way that the Decision service runs. For more information about EPVs, refer to the related topic "Creating exposed process values." 143

7. You can modify or view the properties of an existing variable. Click to highlight the variable name, then modify the variable properties under the Details section, or view the Default Value of the variable if a default value has been defined, as shown in the following example:

8. Select an existing Variable Type, or define a new variable type. A. Click Select to set or modify the current variable type. B. Click New to define a new variable type. For more information about defining a new variable type using the Business Object editor, refer to the related topic "Adding variable types and business objects to a Decision service."

What to do next You must initialize private variables before running the Decision service. In IBM BPM, all private variables must be initialized before you use them in a business process definition or Decision service. If you do not initialize a variable, you may receive runtime errors or notice that the controls to which the variable is bound do not behave as expected. For more information, refer to the related topic, "Initializing complex variables and lists." - Default rule variables and parameters Pre-defined variables and variable types are deployed from the System Data toolkit when IBM Business Process Manager is installed. - Adding variable types and business objects to a Decision service In IBM Business Process Manager, you can create a custom business object (variable type) for the Decision service. The variable type becomes part of the data for the process application, and is available for all business process definitions (BPDs) and services included in the process application.

144

- Variable types You can define a Decision service variable by first specifying the name of the variable, then setting the variable type. The variable value can be a simple data type such as a string, integer, or date. You can also define a complex variable type using a business object that contains parameters. Parent topic:Building a Decision service Related information: Adding variable types and business objects to a Decision service Creating exposed process values (EPVs)

145

Default rule variables and parameters Pre-defined variables and variable types are deployed from the System Data toolkit when IBM® Business Process Manager is installed.

Default Decision service variables The System Data toolkit is imported into the Process Center repository so that each process application and toolkit that you create has access to IBM BPM system data. The System Data toolkit includes assets that all IBM BPM projects require, including variable types. The Decision service can use most of the pre-defined variables and variable types, with a few exceptions. For example, when you create a new variable in the Rule editor, and select a business object (variable type) to associate with the variable, the following list of default variable types is displayed:

The following variable types are not supported for Decision service variables: - SQLResult - XMLDocument - XMLElement - XMLNodeList

Decision service parameters 146

Decision service parameters, which are defined for each business object (variable type) provide a mechanism for exchanging data between a rule component and a process application. You can define Decision service parameters using the following elements: - A business object name - A variable type - A direction, which indicates whether a parameter is used as input to a Decision service, or output from the Decision service, or both. The direction setting is determined automatically based on how the parameter or variable is used in the rule. For example, any parameter or variable that is referenced in a rule, but is not modified or updated when the service is running, is identified as an IN variable. For information about setting up Decision service parameters, see the related topic "Adding variable types and business objects to a Decision service."

Parent topic:Adding and modifying Decision service variables Related information: Adding variable types and business objects to a Decision service

147

Adding variable types and business objects to a Decision service In IBM® Business Process Manager, you can create a custom business object (variable type) for the Decision service. The variable type becomes part of the data for the process application, and is available for all business process definitions (BPDs) and services included in the process application.

Before you begin To perform this task, you must be in the IBM Process Designer desktop editor. To create a custom business object (variable type), you must have write access to a process application or toolkit in the Process Center repository. Access to process applications and toolkits is controlled by users who have administrative rights to the repository.

Procedure To add a business object (variable type) to a Decision service, complete these steps: 1. Open the Process Designer desktop editor. 2. Open a process application that contains the Decision service. 3. You can add a variable type from the library panel, or from the Variables tab while you are working in the Rule service. - To add a business object from the library panel: A. Click the plus sign next to the Data library item. B. In the Create New window, click Business Object. C. In the New Business Object window, type a name for the variable type, then click Finish. D. Follow the procedure steps to define the new business object (variable type). - To add a variable type while working in the Decision service: A. Make sure you are working in the Decision service where you want to add the new variable type. B. Click the Variables tab. C. Create a new variable, or select the variable where you want to add the new variable type. For more information about adding variables, refer to the related topic "Adding and modifying Decision service variables." D. In the Details section, click New next to the Variable Type field. E. In the New Business Object window, type a name for the variable type, then click Finish. F. Follow the procedure steps to define the new business object (variable type). 4. In the Behavior section, select a Definition Type from the list. - Select Simple Type to create a new variable type using an existing type such as String, Decimal, or Integer. For more information about creating simple variable types, refer to the related topic "Creating custom variable types." - Select Complex Structure Type to create a new complex variable type. You can create a custom variable type by adding parameters and parameter properties to the business object. For more information about creating complex variable types, refer to the related topic "Adding process variables to a BPD."As

148

you are adding parameters for a complex structure type, you can see the resulting changes to the XML schema for the variable type. To see how the variable parameters are declared in the XML schema, open the Advanced Properties section and click View XML Schema. 5. When you have entered all the necessary parameters and settings for the variable type, click Save in the main toolbar. 6. Return to the Decision service editing panel, then click Select next to the Variable Type field. The variable type that you added is listed as an available type.

What to do next In IBM BPM, all complex variables must be initialized before you can use the variables in a BPD or service. Refer to the related topic "Initializing complex variables and lists" for more information. Parent topic:Adding and modifying Decision service variables Related information: Creating custom business objects in Process Designer Declaring variables for a BPD or a service in Process Designer

149

Variable types You can define a Decision service variable by first specifying the name of the variable, then setting the variable type. The variable value can be a simple data type such as a string, integer, or date. You can also define a complex variable type using a business object that contains parameters. Declaring the variables for a service enables the service to display and manipulate the values that it receives from (input) and then pushes back up (output) to the main business process.Important: You must initialize complex variable structures before running the Decision service. In IBM® BPM, all complex variables and all lists (arrays) must be initialized before you use them in a business process definition or service. If you do not initialize a complex variable or list, you may receive runtime errors or notice that the controls to which the variables are bound do not behave as expected. For more information, refer to the related topic "Initializing complex variables and lists."

Complex variables for hierarchical data In IBM Business Process Manager, you can create a custom variable type by using a base variable type or by defining a new complex structure. You can create rules about complex data that is nested, or hierarchical. Data that is referenced within the text of a rule is not limited to simple data types such as string, integer, or date. You can create complicated rules with nested variable structure. For example, in the Decision service shown in the following diagram, the variable paymentIn has the variable type Payment, and contains other, nested variables.

For more information about creating complex, hierarchical variable types, see the related topic "Adding process variables to a BPD." There are several complex variable types that are not supported when authoring rules in a Decision service. The unsupported variable types are: - SQLResult

150

- XMLDocument - XMLElement - XMLNodeList

Collections (lists) of variables You can write rules against collections, or lists of variables, using Business Action Language (BAL) rule constructs. You can use a variable to retrieve a collection (list) of objects of a specific type. Use a list parameter in a business object when then are numerous objects that your rule must run against, instead of just a single object. For example, if you are writing a rule about an invoice, and there are multiple line items in the invoice, then the invoice is actually a collection of line items. To write a rule against the number of line items (if there are 10 or more line items, then process this invoice manually), add a list parameter in a complex variable to your rule. In the complex variable type, or business object, shown in the following diagram, PastPayment is a list parameter, which means that it contains multiple objects of the String, Decimal and Date variable type. To identify a variable as a collection or list, click to select the Is List option under Parameter Properties.

Predefined variable types Many pre-defined variable types are provided by the IBM BPM System Data toolkit. These variables are defined as business objects. You can open a business object in Process Designer and review the Documentation field to learn when and how to use each variable type. For example, to open the Record business object included in the System Data toolkit, complete these steps: 1. Open a process application in Process Designer. 2. Click the indicator next to the Toolkits category to see a list of toolkit dependencies for the current process application.

151

3. Click the indicator next to the System Data toolkit to see its contents. 4. Click the Data category 5. Double-click the Record business object to open it. The Documentation field provides information about the business object. The documentation informs you that a Record is a group of ANY typed variables and that you do not need to declare the number of ANY typed variables that you want to go into the Record. So, the Record object is similar to a Structure object, except you do not need to declare the type or the number of variables it contains. For additional information about using variable types in rules, refer to the related topic "Types of variable definition" in the WebSphere ILOG JRules InfoCenter.

Parent topic:Adding and modifying Decision service variables Related information: Declaring variables for a BPD or a service in Process Designer Types of variable definition

152

Testing a Decision service When you have finished creating a Decision service and authoring rules in a rule component, such as a BAL Rule component, you can test the Decision service to determine if the rules are being applied as you intended. If an error or exception occurs within a rule, you will see messages about the error during testing, and you can debug the specific rule component or rule that caused the error.

Before you begin To perform this task, you must be in the IBM® Process Designer desktop editor.

About this task To test a rule component and the rules it contains, you can load the Decision service with default data and then step through the activities in your business process definition to see the generated process data as it interacts with the business rules you have defined. For example, if you set a breakpoint on an activity that has an associated Decision service, you can make sure that the Decision service is producing the data you expect, and make sure that there are no error messages or exceptions being produced by the Decision service as it runs.

Procedure To test a Decision service, complete these steps: 1. Open the Process Designer desktop editor. 2. Open a process application that contains a business process definition (BPD) with a Decision service you want to test. 3. Open the BPD and click to select the activity or decision gateway in the business process that has the Decision service associated with it. 4. Set a breakpoint in the activity. Set breakpoints at specific locations in the process where you want the process flow to pause during testing so that you can determine the status of the process, and identify any errors that might have occurred. 5. Click the Decision service name to open the rules in the rule editor. 6. Click the Run service icon in the banner above the rule editor. 7. When Process Designer prompts you to change to the Inspector interface, click Yes. The Inspector displays red tokens both in the BPD diagram and the execution step tree, which provides a hierarchical view of the execution state, showing the step that is currently running in the active process instance. - Debugging a Decision service Debug a rule component in a Decision service using the Inspector perspective and the debugging feature in Process Designer. Use these testing functions to can examine how the Decision service operates in each step of the process execution, which provides a more detailed inspection than simply stepping through the process. - Exception messages in Decision service testing You can review exception messages that result from Decision service testing. The

153

exceptions provide information that is helpful when you are troubleshooting Decision service execution errors. Parent topic:Building a Decision service

154

Debugging a Decision service Debug a rule component in a Decision service using the Inspector perspective and the debugging feature in Process Designer. Use these testing functions to can examine how the Decision service operates in each step of the process execution, which provides a more detailed inspection than simply stepping through the process.

Before you begin To perform this task, you must be in the IBM® Process Designer desktop editor.

About this task There are several types of Decision service problems that you can troubleshoot using the Debug Service and the Inspector. For example: - Results from running the Decision service are not what you expected. - Running the Decision service results in an exception and you need to identify the process step that generates errors. To enable the Debug Service to step through the Decision service execution, set a breakpoint on each activity within the Decision service before running the debug function.

Procedure 1. Open the Process Designer desktop editor. 2. Open a process application in the Designer view. 3. Make sure that you are working in the Decision service that you want to test and debug. 4. Click the Debug icon. 5. The IBM BPM Debug Service opens in a new browser window, as shown in the following diagram:

6. Click Step in the Debug window to run the Decision service one step at a time, or click Run to run the complete Decision service. 155

7. When Process Designer prompts you to change to the Inspector perspective, click Yes.Note: The prompt to switch to the Inspector perspective might be covered up by the Debug window. 8. The Inspector opens the currently running service in the Services in Debug tab and shows progress through the service, using a hierarchical tree in the Execution State panel to show the process step that is running.

9. When you run a Decision service and an exception occurs, the Inspector clearly identifies the error in the Execution State panel. The Inspector also tells you where the error happened, and links directly to the source of the problem. For more information about using the Inspector to debug errors, see the related topic "Resolving errors." 10. The Debug service browser window captures error and exception messages. The first few lines of the exception are displayed at the top of the browser window. To see the complete message, click Details. To help you locate the rule that produced the error, some exception messages refer to specific rules by their order number, such as Rule 1, Rule 2, Rule 3, prefixed by the name of the Decision service step, as shown in the following example:An error occurred in QuoteLookupRule2 service, at step BalRule1. Detail message: Object stockQ not found at run time during execution. You must make sure that the object has been initialized.

Parent topic:Testing a Decision service Related tasks: Resolving errors

156

Exception messages in Decision service testing You can review exception messages that result from Decision service testing. The exceptions provide information that is helpful when you are troubleshooting Decision service execution errors. When troubleshooting Decision service errors, the following information applies to the exception messages: - When a rule component is running, exception messages include the Decision service name and step name. - Exceptions in a rule condition cannot be traced to a specific rule. - Exceptions in a rule action can be traced to a specific rule. - The rule name includes a number part that corresponds to the order of the rules in the BAL rules component, such as 1, 2, 3, or 4. If there are numerous rules in a BAL rules component, this number helps you track down the location of the error.

Example of a null exception If a variable value cannot be resolved, this problem results in a null exception, as shown in the following example:ilog.rules.res.session.IlrRuleServiceException: ilog.rules.res.session.IlrSessionException: An error occurred while the rule session was invoked.: ilog.rules.res.session.IlrSessionException: An error occurred while the rule session was invoked. ilog.rules.res.util.IlrRemoteException: Ruleset execution error ilog.rules.res.util.IlrRemoteException: null at call to 'mainRuleflow flow task body' at call to 'execute' ilog.rules.res.util.IlrRemoteException

at ilog.rules.res.session.IlrRuleService.executeRuleset(IlrRuleService.java:124) at com.ibm.rules.sdk.samples.documentrules.ResultsTab$4.widgetSelected(ResultsTab.java:206) at org.eclipse.swt.widgets.TypedListener.handleEvent(TypedListener.java:234) at org.eclipse.swt.widgets.EventTable.sendEvent(EventTable.java:84) at org.eclipse.swt.widgets.Display.sendEvent(Display.java:3776) at org.eclipse.swt.widgets.Widget.sendEvent(Widget.java:1367) at org.eclipse.swt.widgets.Widget.sendEvent(Widget.java:1390) at org.eclipse.swt.widgets.Widget.sendEvent(Widget.java:1375) at org.eclipse.swt.widgets.Widget.notifyListeners(Widget.java:1187) at org.eclipse.swt.widgets.Display.runDeferredEvents(Display.java:3622) at org.eclipse.swt.widgets.Display.readAndDispatch(Display.java:3277) at org.eclipse.ui.internal.Workbench.runEventLoop(Workbench.java:2629) at org.eclipse.ui.internal.Workbench.runUI(Workbench.java:2593) at org.eclipse.ui.internal.Workbench.access$4(Workbench.java:2427) at org.eclipse.ui.internal.Workbench$7.run(Workbench.java:670) at org.eclipse.core.databinding.observable.Realm.runWithDefault(Realm.java:332) at org.eclipse.ui.internal.Workbench.createAndRunWorkbench(Workbench.java:663) at org.eclipse.ui.PlatformUI.createAndRunWorkbench(PlatformUI.java:149) at com.ibm.rules.sdk.samples.documentrules.Application.start(Application.java:38) at org.eclipse.equinox.internal.app.EclipseAppHandle.run(EclipseAppHandle.java:196)

157

at org.eclipse.core.runtime.internal.adaptor.EclipseAppLauncher.runApplication(EclipseAppLauncher.java:110) at org.eclipse.core.runtime.internal.adaptor.EclipseAppLauncher.start(EclipseAppLauncher.java:79) at org.eclipse.core.runtime.adaptor.EclipseStarter.run(EclipseStarter.java:369) at org.eclipse.core.runtime.adaptor.EclipseStarter.run(EclipseStarter.java:179) at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method) at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:39) at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:25) at java.lang.reflect.Method.invoke(Method.java:597) at org.eclipse.equinox.launcher.Main.invokeFramework(Main.java:619) at org.eclipse.equinox.launcher.Main.basicRun(Main.java:574) at org.eclipse.equinox.launcher.Main.run(Main.java:1407) at org.eclipse.equinox.launcher.Main.main(Main.java:1383) Caused by: ilog.rules.res.session.IlrSessionException: An error occurred while the rule session was invoked.: ilog.rules.res.session.IlrSessionException: An error occurred while the rule session was invoked. ilog.rules.res.util.IlrRemoteException: Ruleset execution error ilog.rules.res.util.IlrRemoteException: null at call to 'mainRuleflow flow task body' at call to 'execute' ilog.rules.res.util.IlrRemoteException

Unsupported variable type If you author a rule that uses an unsupported variable type, an exception message similar to the following example is displayed:An error occurred in simpleTypeTestService service, at rule 1 in step SimpleTypeRuleStep. Detail message: Ruleset /b_c54531e1028c40a185bf1115183a3420/1.0/_bd1ea7af45d14fa9afcea38113db2c35_8cf262cc674e4561bce84c00820bc88e/1.0 parsing failed 'IRL/rule_1.irl', line 8: error: incompatible values involved in assignments com.lombardisoftware.core.TeamWorksException: An error occurred in simpleTypeTestService service, at rule 1 in step SimpleTypeRuleStep. Detail message: Ruleset /b_c54531e1028c40a185bf1115183a3420/1.0/_bd1ea7af45d14fa9afcea38113db2c35_8cf262cc674e4561bce84c00820bc88e/1.0 parsing failed 'IRL/rule_1.irl', line 8: error: incompatible values involved in assignments at com.lombardisoftware.core.TeamWorksException.asTeamWorksException(TeamWorksException.java:129) at com.lombardisoftware.core.RegexExceptionRewriter.rewrite(RegexExceptionRewriter.java:76) at com.lombardisoftware.core.ExceptionHandler.returnProcessedException(ExceptionHandler.java:310)

Uninitialized variable produces a NullPointerException Using an uninitialized variable in a BPEL process can result in various exception errors. In IBM® BPM, all private or complex variables and all lists (arrays) must be initialized before you use them in a business process definition or Decision service. If you do not initialize a private or complex variable or list, you may receive runtime errors, such as the following example, or notice that the Coach controls to which the variables are bound do not behave as expected. For more information about errors produced by uninitialized variables, refer to the related topic "Uninitialized variable or NullPointerException in a Java snippet."An error occurred in NotificationRules service, at rule 1 in step AlertRuleStep.

158

Detail message: Object CustomerName not found at run time during execution. Make sure the object has been initialized. at com.lombardisoftware.core.TeamWorksException.asTeamWorksException(TeamWorksException.java:129) at com.lombardisoftware.core.RegexExceptionRewriter.rewrite(RegexExceptionRewriter.java:76) at com.lombardisoftware.core.ExceptionHandler.returnProcessedException(ExceptionHandler.java:310) at com.lombardisoftware.servlet.ControllerServlet.doError(ControllerServlet.java:152) at com.lombardisoftware.servlet.ControllerServlet.doCommon(ControllerServlet.java:417) at com.lombardisoftware.servlet.ControllerServlet.doPost(ControllerServlet.java:134) at javax.servlet.http.HttpServlet.service(HttpServlet.java:738) at javax.servlet.http.HttpServlet.service(HttpServlet.java:831)

Parent topic:Testing a Decision service Related information: Uninitialized variable or NullPointerException in a Java snippet

159

Scenario: Exporting rules to a Rule Execution Server This scenario shows you how to export, migrate and connect BAL rules to a rule execution server (RES). You can migrate the rules that you created in Process Designer to a business rules management system (BRMS) such as IBM® WebSphere® ILOG® JRules, and then continue to use the rules in a business process definition.

About this task This scenario assumes that you previously completed the steps outlined in Scenario: Creating a Decision service in a Personalized Notification process. Upon completion of that scenario, your business process definition includes a Decision service called NotificationRulesService, which contains a BAL Rule component called AlertRules. For the purposes of the current exporting scenario, assume that the rules you wrote for the AlertRules component also apply to other processes in your organization, so you want to share the rules with your co-workers, who are developing business rules using IBM WebSphere ILOG JRules. You can export the rules you created in Process Designer, import them into Rule Studio, deploy the rules to a Rule Execution Server (RES) , and then connect your Decision service to the RES using a JRules Decision Service component.

Procedure To export rules for use in Rule Studio and the Rule Execution server, complete these steps: 1. Export the BAL rules from your Decision service. A. Make sure that you are editing the NotificationRulesService Decision service and the AlertRules BAL Rule component. B. In the AlertRules component panel, click the Decisions tab to open the rule editor. C. In the menu bar above the rule editor window, click the Export icon. D. In the Save As window, navigate to the location where you want to save the exported rule file. E. Enter a name for the export file, then click Save to specify the location. You can find more information about exporting rules in the related topic about exporting rules for use in Rule Studio. 2. Import the rules into Rule Studio. A. Using IBM WebSphere ILOG Rule Studio, import the project .zip file to create a new Rule Studio project. B. Click File > Import > General > Existing Projects into Workspace. C. Click Select archive file. Click Browse to navigate to the location where you saved the exported rule project file and select the file. D. Select an existing project where the rules will be imported, or create a new Rule Studio project, then click Finish. You can find more information about importing rules in the related topic about configuring a remote decision service.

160

3. Deploy the rules to the rule execution server (RES). A. In Rule Studio, select the RuleApp which contains the AlertRules and click Deploy a RuleApp to one or more Rule Execution Servers. B. Select an existing Rule Execution Servicer and deploy the RuleApp to the server. For more information, see the related topic about deploying from Rule Studio in the IBM WebSphere ILOG JRules BRMS Information Center. 4. Add a JRules Decision Service component the Decision service and connect it to the RES. A. Configure your Decision service to include a JRules Decision Service component. When you specify the correct rule execution server and port settings, the JRules Decision component establishes a connection between Process Designer and the Rule Execution Server that contains the imported rule project. B. Make sure that you are editing the NotificationRulesService Decision service. C. Remove the AlertRules BAL Rule component that contains the rules you exported. D. Replace the BAL Rule component with a JRules Decision Service component. Drag a JRules Decision Service component from the palette to the service diagram, and place it in the same location as the deleted BAL Rule component. Reconnect any sequence lines to other activities or services. E. Select the new JRules Decision Service component, then click Implementation in the Properties tab. F. In the Discovery section, enter the following information to connect to the Rule Execution Server that contains the rules that you want to use. - Server: Select the Rule Execution Server (RES). - SOAP Port: Specify a port for the SOAP connection if the Rule Execution Server is running on WebSphere Application Server. - User name: Enter a user name if the JRules server requires a secure connection. - Password: Enter the password if the JRules server requires a secure connection. G. Click Connect. H. In the Rule section, select the Rule App that you want from the menu, then select the version that you want to use. I. Click Generate Types. You can find more information about adding a JRules Decision Service component in the related topic about configuring a remote Decision service. 5. Map the variables to make sure that the variables used in the rules on the Rule Execution Server correspond to variables defined in Process Designer. A. Click the Properties tab in the JRules Decision Service panel. B. In the Properties section, click Data Mapping. C. Click the auto-map icon in upper right corner of the Input Mapping section. D. In the Create variables for auto-mapping window, click to select each variable that you want to create in your Decision service and then click OK. E. Click the auto-map icon in upper right corner of the Output Mapping section. F. In the Create variables for auto-mapping window, click to select each variable that you want to create in your Decision service and then click OK. 161

6. Save the updated Decision service.

What to do next After completing the scenario, test and debug the Decision service and the JRule Decision service component to make sure the rules from the Rule Execution Server are producing the results you expect. For more information about testing and debugging a Decision service, see the related topic about testing a Decision service. Parent topic:Building a Decision service Related information: Exporting rules for use in Rule Studio Configuring a remote Decision service Deploying from Rule Studio Testing a Decision service

162

Exporting rules for use in Rule Studio You can export a set of rules to create a project file that you can then import and work on in IBM WebSphere ILOG JRules Rule Studio.

Before you begin To perform this task, you must be in the IBM® Process Designer desktop editor.

About this task Process Designer provides the capability for non-developers to express business logic using Business Action Language (BAL) in business rules. In most cases, business rules can be fully developed and implemented using Process Designer. However, in a situation where the business logic reaches levels of complexity not supported within IBM Business Process Manager, the business logic can be exported without modifications to IBM WebSphere ILOG JRules Rule Studio. The export procedure produces a complete business rules project suitable for continued work within JRules. After exporting the rules, importing into Rule Studio, and deploying the rules on a Rule Execution Server, the business process in Process Designer can consume the resulting rule application using a remote decision service provided by JRules.

Procedure To export a rule component that contains a single rule or multiple rules, complete these steps: 1. Open the Process Designer desktop editor. 2. Open a process application in the Designer view. 3. Make sure that you are working in the Decision service that contains the rule component you want to export. 4. In the Decision service diagram, click to select the component icon, such as a BAL Rule, that represents the component you want to export. 5. Click the Decisions tab. 6. In the menu bar at the top of the rule editor window, click the Export icon. 7. In the Save As window, navigate to the location where you want to save the exported rule file. 8. Enter a name for the export file, then click Save.

Results The export function produces an Eclipse project file with a .zip extension.

What to do next You can import the rule project file into ILOG Rule Studio. To keep the Decision service connected to the rules as you work on them in Rule Studio, you can replace the BAL Rule in the Decision service with a JRule Decision Service. Refer to the related topic "Configuring a remote Decision service" for information about performing this procedure. For more information about importing a rule project into ILOG Rule Studio, refer the related topic "Importing a rule project in Rule Studio" in 163

the WebSphere ILOG JRules InfoCenter. - Configuring a remote Decision service You can include a rule application from a remote ILOG JRules Rule Execution Server in your Decision service. Parent topic:Building a Decision service Related information: Importing a rule project in Rule Studio

164

Configuring a remote Decision service You can include a rule application from a remote ILOG JRules Rule Execution Server in your Decision service.

Before you begin - Export the rules to an Eclipse rule project file. - Using IBM WebSphere ILOG Rule Studio, import the project .zip file to create a new Rule Studio project. 1. Click File > Import > General > Existing Projects into Workspace. 2. Click Select archive file. Click Browse to navigate to the location where you saved the exported rule project file and select the file. 3. Select an existing project where the rules will be imported, or create a new Rule Studio project, then click Finish. 4. Deploy the imported rules to the Rule Execution Server. For more information, see the related topic "Deploying from Rule Studio." A related link is provided.

About this task After you have exported rules in a rule component from IBM® Business Process Manager, and imported the rule project into IBM WebSphere ILOG Rule Studio, you can configure your Decision service to include a JRules Decision Service component. When you specify the correct rule execution server and port settings, the JRules Decision component establishes a connection between Process Designer and the Rule Execution Server that contains the imported rule project.

Procedure 1. Make sure that you are working in the Decision service where you want to add the JRules Decision Service. 2. Remove the BAL Rule component that contains the rules you exported. 3. Drag a JRules Decision Service component from the palette to the service diagram, and place it in the same location as the deleted BAL Rule component. Reconnect any sequence lines to other activities or services. 4. Select the new JRules Decision Service component, then click Implementation in the Properties tab. 5. In the Discovery section, enter the following information to connect to the Rule Execution Server that contains the rules that you want to use.Table 1. Input required to connect to the Rule Execution Server Field Server

SOAP Port

Action Select the server that you want from the list of ILOG Rules Server variables. See the related topic "Setting environment variables" for more information. Specify a port for the SOAP connection if the Rule Execution Server is running on WebSphere® Application Server. 165

User name Password

Enter a user name if the JRules server requires a secure connection. Enter the password if the JRules server requires a secure connection.

The SOAP port, user name, and password fields accept embedded JavaScript expressions, so variables can be used to provide those values. 6. Click Connect. 7. In the Rule section, select the Rule App that you want from the menu, then select the version that you want to use. If a secure connection to the Rule Execution Server has not been established, the menu is not populated. In this case, manually enter the name and version of the Rule App and Rule Set that you want to use. The names must be accurate for the next step to work. 8. Click Generate Types. 9. In the Generating Types window, make sure that the Generate request/response wrapper types option is not selected. Click Next. 10. Click Finish when type generation is complete. 11. In the Properties section, click Data Mapping. 12. Click the auto-map icon in upper right corner of the Input Mapping section. The Create variables for auto-mapping window opens, listing the private variables needed for input parameters from the selected Rule App. 13. Click to select each variable that you want to create in your Decision service and then click OK. 14. Click the auto-map icon in upper right corner of the Output Mapping section. The Create variables for auto-mapping window opens, listing the private variables needed for output parameters from the selected Rule App. 15. Click to select each variable that you want to create in your Decision service and then click OK. 16. Save the updated Decision service. Parent topic:Exporting rules for use in Rule Studio Related information: Deploying from Rule Studio

166

Adding a JRules Decision Service component to a service When building a Decision service in Process Designer, you can include decision services available on an ILOG JRules Rule Execution Server in your implementation.

Before you begin To perform this task, you must be in the IBM® Process Designer desktop editor.

About this task IBM Business Process Manager integrates with IBM WebSphere ILOG JRules by providing a JRules Decision Service component. This rule component enables you to use rule applications available on a JRules Rule Execution Server for your IBM BPM implementations. Why should you choose using a JRules Decision Service component over creating a standard web service when connecting to an IBM Operational Decision Management (ODM) server, which is IBM’s recently renamed ILOG JRules Rule Execution Server? The JRules Decision Service component is specifically designed for calling a JRules decision service. It has a closer conceptual mapping to the JRules decision service called and, therefore, is a more efficient representation of it in your business process model. A JRules Decision Service component can handle decision services hosted on either a WebSphere ILOG JRules BRMS 7.1, WebSphere Operational Decision Management 7.5, or IBM Operational Decision Management server. Conversely, the web service will treat the service called as it would any other generic service; that is, the web service has no corresponding model representing the JRules decision service called. Each time a JRules server version changes, you will need to modify the web service. The following procedure describes how to use the JRules Decision component to connect to a WODM server and invoke the rule applications and rule sets available on that server as decision services. Before using the JRules Decision Service component in your Rules service, review the following requirements: - For a secure connection to a Rule Execution Server running on WebSphere® Application Server, you must provide the SOAP port and, if necessary, the user name and password for the Rule Execution Server. This secure connection enables you to choose the applications and rule sets that you want to use from the Rule Execution Server. - If you connect to a Rule Execution Server that is running on WebSphere Application Server, but the Rule Execution Server is not properly configured for security or you are not able to provide the SOAP port, user name, and password, then you cannot list the rule applications and rule sets available on that Rule Execution Server. In this case, you can manually enter the names of the rule applications and rule sets that you want to use. If the names that you provide are accurate, you can successfully generate types as described in the following

167

procedure. - If you connect to a Rule Execution Server that is running on an application server other than WebSphere, you cannot list the rule applications and rule sets available on that Rule Execution Server. In this case, you can manually enter the names of the rule applications and rule sets that you want to use. If the names that you provide are accurate, you can successfully generate types as described in the following procedure.

Procedure To build a Decision service that includes an JRules Decision Service component, complete these steps: 1. Open the Process Designer desktop editor. 2. Open a process application in the Designer view. 3. Create a Decision service. 4. Drag a JRules Decision Service component from the palette to the service diagram. 5. With the JRules Decision Service component selected, click the Implementation option in the Properties tab. 6. In the Discovery section, enter the following information to connect to a Rule Execution Server that contains deployed rule applications (Rule Apps) that you want to use.Table 1. Input required to connect to the Rule Execution Server Field Server SOAP Port User name Password

Action Select the server that you want from the list. Specify a port for the SOAP connection if the Rule Execution Server is running on WebSphere Application Server. Enter the user name to use, if necessary, for a secure connection. Enter the password to use, if necessary, for a secure connection.

The SOAP port, user name, and password fields accept embedded JavaScript expressions, so variables can be used to provide those values. 7. Click Connect. 8. In the Rule section, select the Rule App that you want from the menu, then select the version that you want to use. If a secure connection to the Rule Execution Server has not been established, the menu is not populated. In this case, manually enter the name and version of the Rule App and Rule Set that you want to use. The names must be accurate for the next step to work. 9. Click Generate Types. 10. In the Generating Types window, make sure the Generate request/response wrapper types option is not selected. Click Next. 11. Click Finish when type generation is complete. 12. In the Properties section, click Data Mapping.

168

13. Click the auto-map icon in upper right corner of the Input Mapping section. The Create variables for auto-mapping window opens, listing the private variables needed for input parameters from the selected Rule App. 14. Click to select each variable that you want to create in your Decision service and then click OK. 15. Click the auto-map icon in upper right corner of the Output Mapping section. The Create variables for auto-mapping window opens, listing the private variables needed for output parameters from the selected Rule App. 16. Click to select each variable that you want to create in your Decision service and then click OK. 17. Use sequence lines to connect the JRules Decision Service component to the Start and End Events. 18. Save the new Decision service.

What to do next You can nest this Decision service in any other service within your process application that requires the same logic. Be sure to adjust the input and output variables as required for each implementation. Refer to the related topic "Declaring and passing variables" for more information.

Parent topic:Building a Decision service Related information: Adding a server configuration Adding a Decision service to a process Declaring and passing variables

169

Adding a Decision Table component to a service You can add a Decision Table component to a service.

Before you begin To perform this task, you must be in the IBM® Process Designer desktop editor.

About this task The Decision Table component contains a table with a rule condition in each row. Each row in the table represents a Boolean condition that will evaluate to true or false at run time. The condition evaluates to true only if the values of all the associated variables produce matches with the provided values. The following information applies to the Decision Table component. - The double-dash (-) value in a variable field indicates that any variable value is considered a match. - When a rule evaluates to true, the JavaScript expression that you provide as the action is started. This expression may contain any valid JavaScript. - A rule only executes the JavaScript expression once per a rule, using the JavaScript expression associated with the first condition that evaluates to true. The steps in this procedure demonstrate how to add a Decision Table component to a decision service using example values. For your own implementation, you might not use the same steps or names.

Procedure 1. 2. 3. 4.

Open the Process Designer desktop editor. Open a process application that contains a business process definition (BPD). Create a Decision service. Drag the Decision Table component from the component palette to the service diagram. 5. Click the Properties tab, then enter ExpenseApproval as the Decision Table component name. 6. Click the Variables tab. 7. Click Add Input to add variables to the service. 8. Replace Untitled1 in the Name field with request. 9. Click Select next to Variable Type and select the type from the list.If you use the Activity Wizard to create a Decision service, you can choose existing variables to add as input and output. You should use the Activity Wizard when you start with an existing activity and want to quickly create a service to implement the activity. To access the wizard, right-click an activity and select Activity Wizard from the list of options. 10. Click Add Private. 11. Replace Untitled1 in the Name field with approvalRequired . 12. Click Select next to Variable Type and select the Boolean type from the list. 13. Click the Decisions tab to open the rules editor.

170

14. In the rules editor, click the plus sign to add a variable (column) to the first rule (row). 15. From the list of available variables, select amount from the request structure. 16. Type >250 as the variable value. 17. In the rules editor, click the plus sign again. Make sure the first rule (row) is selected because you want to add another variable (column) to this rule. 18. From the list of available variables, select type from the request structure. 19. Type "director" as the variable value. 20. In the Action Requirement field for the first rule (row), type Requires Approval . 21. In the rules editor, click the Action section to expand it. 22. For the Requires Approval requirement, enter the following JavaScript for the Action: tw.local.approvalRequired = true; 23. In the rules editor, click the second row to select it. Create a new rule stating that employee expenses of more than $60 require approval. 24. In the rules editor, click the third row to select it. Create a catch-all rule by typing - for both the amount and type. The - value in a variable field indicates that any variable value is considered a match. 25. In the Action Requirement field for the third rule (row), type Auto Approval . 26. In the Action section, enter the following JavaScript for the Auto Approval action:tw.local.approvalRequired = false; 27. Click the Diagram tab. 28. Use the Sequence Flow tool to connect the Decision Table component and the Start and End events. - Authoring rules using JavaScript in a Decision Table component You can create rules using JavaScript in a Decision Table component. - Decision Table controls You can use the toolbar options in the conditions editor window to add, remove, or move conditions in the table. - Specifying variable values using JavaScript You can use JavaScript in rules to set variable values. Parent topic:Building a Decision service Related information: Adding a Decision service to a process Declaring variables for a BPD or a service in Process Designer

171

Authoring rules using JavaScript in a Decision Table component You can create rules using JavaScript in a Decision Table component.

Before you begin To perform this task, you must be in the IBM® Process Designer desktop editor.

About this task The following steps describe how to create a sample business rule using the Decision Table editor and JavaScript. The rule in the sample is used to determine whether approval is required for certain employee expenses. The sample is a singlefunction rule that can be called from any other service. For your own implementation, you might not use the same steps or names.

Procedure 1. 2. 3. 4.

Open the Process Designer desktop editor. Open a process application that contains a business process definition (BPD). Create a Decision service. Drag a Decision Table component from the palette to the Decision service diagram, and edit the component parameters as described in the related topic "Adding a Decision Table component to a service." 5. Click the Decisions tab to open the rules editor. 6. In the rules editor, click the plus sign to add a variable (column) to the first rule (row). 7. From the variables displayed, pick the amount variable from the request structure. 8. Type >250 as the value. 9. In the rules editor, click the plus sign again. Make sure the first rule (row) is selected because you want to add another variable (column) to this rule. 10. From the variables displayed, pick the type variable from the request structure. 11. Type "director" as the value. 12. In the Action Requirement field for the first rule (row), type Requires Approval. 13. In the rules editor, click the Action section to expand it. 14. For the Requires Approval requirement, enter the following JavaScript code for the Action: tw.local.approvalRequired = true; The rules editor includes the rule shown in the following image:

172

15. In the rules editor, click the second row to select it. Create a new rule so that expenses of more than $60 for employees requires approval. 16. In the rules editor, click the third row to select it. Create your catch-all condition by typing - for both the amount and type. The - value in a variable field indicates that any variable value is considered a match. 17. In the Action Requirement field for the third rule (row), type Auto Approval. 18. In the Action section, enter the following JavaScript for the Auto Approval action: tw.local.approvalRequired = false; The rules editor includes the rules shown in the following image:

For more information about specifying variable values using JavaScript, refer to the related topic "Specifying variable values using JavaScript." 19. Click the Diagram tab. 20. Use the Sequence Flow tool to connect the Decision Table component and the Start and End events. 21. Name the Decision Table component and save your work.

What to do next You can now nest this Decision service in any other service within your process application that requires this logic. Be sure to adjust the input and output variables as required for each implementation. For more information about the controls in the decisions editor window, such as the up and down arrows, refer to the related topic "Decision Table controls."

Parent topic:Adding a Decision Table component to a service Related information: Adding a Decision service to a process Adding a Decision Table component to a service

173

Decision Table controls You can use the toolbar options in the conditions editor window to add, remove, or move conditions in the table. Table 1. Toolbar options in the conditions editor window Option

Description Add a new variable (column) or remove the selected variable (column) from the rule. Move the selected rule (row) up or down in the table or remove the selected rule (row) from the table.

Parent topic:Adding a Decision Table component to a service

174

Specifying variable values using JavaScript You can use JavaScript in rules to set variable values. The following samples demonstrate how to specify the value of a variable when using the rules editor: Table 1. Samples for setting variable values Sample "ok" 1.4 {"A", "B"} !={"A", "B"} 1..5 >3 =3 Save All

Results An advanced integration service can be used as implementation of a user task or a system task. If used by a user task, it is assigned as specified via the assignments of the user task. If used by a system task, it is run by the system user. An advanced integration service can also be emulated. In emulation, it behaves in the following way: - If used by a user task, it is assigned as specified via the Assignments of the user task. - If used by a system task then it will use the All users group. When All users is shown in emulation, any user selected will require authentication. Select the user you are currently authenticated as and enter your credentials. 187

As discussed earlier, your service is a collaborative arrangement. Should you move your advanced integration service to another toolkit, notify the integration developer who implemented your service. Your service and its implementation by Integration Designer are decoupled, which means that even though you may move a service in Process Designer there will not be an automatic corresponding movement in the implementation by Integration Designer. The integration developer should use the refresh function to identify the implementation that he needs to move and recouple with the advanced integration service you moved in Process Designer.

What to do next Use the information in Authoring services in IBM Integration Designer to continue developing your advanced integration service. You can add services, service-related functions, BPEL processes. monitor models, and more. Parent topic:Building services

188

Building a General System service Use General System services when you want to orchestrate other background services, manipulate variable data, generate HTML for a Coach, or perform some other actions that do not require any integrations or business rules. Prerequisite: To build a General System service, you must be in the IBM® Process Designer desktop editor. General system services are likely to be called directly from a BPD or from a Human Service. General System services can include only basic service components, such as scripts, and cannot contain Coaches or integration steps (Web Service integration, Java integration, or Content integration). General System services can be nested within any other type of service. To create services, you must have access to a process application or toolkit in the Process Center repository. Access to process applications and toolkits is controlled by users who have administrative rights to the repository. For more information, see Managing access to the Process Center repository. To create a General System service, perform the following steps. 1. Open the Process Designer desktop editor. 2. Open a process application in the Designer view. 3. Click the plus sign next to Implementation, and then click General System Service. 4. In New Service, enter a name for the service and click Finish.IBM Process Designer displays the diagram of the service with the default Start Event and End Event components. Parent topic:Building services Related information: Examples of building services with heritage coaches Service types

189

Modeling events Events in IBM Business Process Manager can be triggered by a due date passing, an exception, or a incoming message from an external system. You can add events to your BPDs that can occur at the beginning, during, or at the end of a process. Use events to track data, manage errors, and retrieve information about the execution of your BPDs. - Event types Learn about the types of events available in IBM BPM and when to use each type. - Modeling delays, escalations, and timeouts by using timer events To specify when an activity occurs or when another path in the process should be taken, use intermediate and boundary events of the timer type. - Modeling message events Use a message event to represent a point in your process where an incoming message is received or where an outgoing message is sent. - Enabling users to perform ad hoc actions (deprecated) Use an ad hoc event when you need to include ad hoc actions that can be run at any time during process execution. - Modeling event gateways Use an event gateway to model a point in the process execution where only one of several paths can be followed, depending on events that occur. - Handling errors using error events When you design a business process definition (BPD) or a service, provide logic to recover from possible errors that might be generated in the runtime application. - Using Service Component Architecture to interact with processes There are several ways to start and interact with business process definition (BPD) instances using Service Component Architecture (SCA). You can use receiving message events to create or interact with BPD instances. - Undercover agents An undercover agent (UCA) is attached to a message event or a content event in a business process definition (BPD) and calls a service to handle the event. Parent topic:Modeling processes

190

Event types Learn about the types of events available in IBM® BPM and when to use each type. You can include the following types of events in your IBM BPM Business Process Definitions (BPDs): - Start event - Use to model the start of a process, a linked process, a subprocess or an event subprocess. A Start event is automatically included each time you create a business process definition (BPD). A BPD can include multiple Start events (one Start event with an implementation of None and multiple Start events with an implementation of Message) if you need to be able to start the process more than one way. Start events have the following implementation options: Table 1. Implementation options for Start events Option None

Description Use the None implementation option if you want to enable process participants to start a process manually from IBM Process Portal. (For an example of such a process, see Creating a business process definition (BPD).) Or, you can use this implementation option when you intend to use a process as a linked process from another higher level process. Use the Message implementation option if you want an incoming message to kick off a process (see Using start message events ) or an event subprocess (see Modeling event subprocesses). Use the Ad Hoc implementation option when you need to include ad hoc actions that can be run at any time during process execution. For example, you can include an ad hoc event to enable users to cancel a customer order at any time during the ordering process. See Deprecated: Enabling users to perform ad hoc actions for more information. Use the Content implementation option if you want an ECM event to kick off a process.

Message

Ad Hoc

Content

.Note: For information about implementation options for Start events in a subprocess or event subprocess, see Subprocess types. - Intermediate event

191

- Intermediate events can be attached to activities within your BPDs or they can be included in the process flow, connected with sequence flows. Attached intermediate events are known as boundary events.Intermediate events have the following implementation options:Table 2. Implementation options for Intermediate events Option Message

Description Use the Message implementation option to model a message event that is received or sent. The Message implementation option is available for events included in the process flow and events attached to an activity. When attached to an activity, the event receives only messages. See Using intermediate and boundary message events to receive messages and Using intermediate message events and message end events to send messages for more information. Use the Timer implementation option to model escalation paths or delays in your BPDs. Using a timer event, you can specify a time interval after or before an activity is performed. The Timer implementation option is available for events included in the process flow and events attached to an activity. See Modeling timer events for more information. Use the Tracking implementation option to indicate a point in a process at which you want IBM BPM to capture the runtime data for reporting purposes. The Tracking implementation option is available only for events included in the process flow. Use the Error implementation option to catch errors and to handle errors with login in the process flow. The Error implementation option is available only for events attached to an activity. For an example of how to use intermediate error events, see Handling errors using error events. Use the Content implementation option to model an ECM event that is received. The Content implementation option is available for events included in the process flow and events attached to an activity.

Timer

Tracking

Error

Content

192

- End event - Use to model the end of a process. An End event is automatically included each time you create a BPD.End events have the following implementation options:Table 3. Implementation options for End events Option None

Description Use the None implementation option when you want to indicate the end of activities on a particular path. Use the Error implementation option when you want to throw an error to parent processes or to error event subprocesses. See Handling errors using error events for more information. Use the Terminate implementation option when you want to close running tasks associated with a process and cancel outstanding timers. You can set these options for the terminate event: Terminate Entire Process InstanceTerminates the entire process instance. If you do not select this option, only the process that contains the event and its subprocesses is terminated. If an entire process instance is terminated, the process shows a status of Terminated in the Inspector. Delete All Terminated Instance Runtime DataCleans up the runtime state for the executing instance. All database states for the runtime instance and any generated tracking data is deleted. This setting only applies to top-level process instance cleanup, and is ignored otherwise. Use the Message implementation option when you want to send a message. For example, you might want to send a message at the conclusion of each process instance that is received by a start message event in another process or processes so that the completion of one process starts another related process or processes. See Using message end events for more information.

Error

Terminate

Message

193

Parent topic:Modeling events

194

Modeling delays, escalations, and timeouts by using timer events To specify when an activity occurs or when another path in the process should be taken, use intermediate and boundary events of the timer type.

Before you begin To perform this task, you must be in the IBM® Process Designer desktop editor.

About this task In a business process definition (BPD), use timer events to control when activities occur within a process flow or when a process flow takes a specific path. That is, use timer events to do the following things: - Create a delay to prevent an event or activity from immediately triggering. - Create an escalation to handle when an activity fails to complete in a timely fashion. - Create a timeout to prevent a flow from waiting indefinitely. Each timer event has an associated timer. The time interval for the timer is calculated according to the configuration that you specify in the implementation properties for the timer event. Normally, when the specified time interval elapses, the timer event triggers and the sequence flow goes out from the timer event to a subsequent node. However, when a BPD instance suspends, the timer events do not trigger. All of the timers within the timer events continue to track the passage of time though. If any timers elapse while the instance is suspended, their associated timer events wait for the BPD instance to resume before they trigger. For modeling delays, use timer intermediate events that have sequence flow lines that are entering it and sequence flow lines that are leaving it.

The process waits for the timer in the timer event to elapse before it proceeds to the next node. For example, if your BPD has an activity that emails offers to customers and an activity that has the sales team contact these customers two days later, model a delay by using a timer intermediate event between the two activities. The delay ensures that two days pass between the emails and when the sales team starts contacting the customers. For modeling escalations, use timer boundary intermediate events. Timer boundary

events are attached to an activity in a BPD. When a running process instance reaches an activity that has a timer boundary event, a timer starts. When the timer elapses, the process follows the sequence flow 195

from the timer boundary event to a subsequent activity. For an example, see Hiring tutorial: Add a timer intermediate event in the Hiring Tutorial or see the Hiring Sample. For modeling timeouts, use timer intermediate events that are included in event gateways. If the other intermediate events in the event gateway group do not trigger before the timer elapses, the timer intermediate event triggers instead. When you add an event gateway, Process Designer automatically adds a timer intermediate event and a message event to the event gateway group. You configure the timer

intermediate event to specify the timeout period. For information about creating an event gateway, see Modeling event gateways.

Procedure To model a delay, escalation, or timeout: 1. Open the Process Designer desktop editor. 2. Open a BPD in the Designer view. 3. Drag an intermediate event from the palette. - To create a delay, drop the intermediate event into a blank area of the canvas. - To create an escalation, drop the intermediate event onto an activity. This action attaches the intermediate event as a boundary event. To verify that you have created a boundary event, select the activity and check that the outline of the activity includes the event icon.To have multiple escalations, attach more than one intermediate events to the activity. Each boundary event triggers a different escalation path. - To create a timeout, drop the intermediate event into an event gateway group. 4. Select the intermediate event and open its Implementation properties. 5. From the list of Intermediate Event types, select Timer. 6. If you are creating an escalation and you want the activity to remain open after the timer is triggered, in the Boundary Event Details section clear the Interrupt Activity check box. For example, imagine that you create a timer boundary event for a user task. The human service that is associated with the user task has coaches. If you want the users to complete the coaches even after the timer elapses, clear the Interrupt Activity check box. If you clear the Interrupt Activity check box, you can choose to have the escalation occur only once by clearing the Repeatable check box. 7. Specify when to start the timer for the timer event by setting the Timer properties: A. Set what starts the timer with the Trigger On field. For example, to start the timer when the due date for an activity elapses, select After Due Date. The due date is calculated according to the work schedule for the BPD and the priority settings for the activity. For more information, see Setting the work schedule for a BPD. Note: To trigger the timer event before or after a custom 196

date, you can enter the JavaScript to determine the custom date in the Custom Date field. Your JavaScript must return a Date object, which specifies when to start the timer. B. Optional: To modify the trigger, use the Before or after difference field. For example, if you want start the timer a day after the due date of the activity, type 1 into the field and select Days from the associated list. C. Optional: To further modify the trigger, use the Tolerance Interval field. For example, specify a tolerance level of one hour if you want the escalation to occur one day and one hour after the due date of the activity. 8. If you are creating an escalation or timeout, create the flow that the process uses after the timer elapses. The escalation path is the logic that the process performs if the timer elapses before the activity it is attached to finishes. Similarly, the timeout path is the logic that the process performs if the timer elapses before another event in the event gateway group triggers. 9. Connect the timer event: - For a delay, use the Sequence Flow tool to connect the timer event to the rest of the process. - For an escalation or timeout, connect the timer event to the escalation or timeout path. Parent topic:Modeling events Related information: Hiring tutorial

197

Modeling message events Use a message event to represent a point in your process where an incoming message is received or where an outgoing message is sent. Prerequisite: To model message events, you must be in the Process Designer desktop editor. Incoming messages can originate from a message event in a process, from starting an undercover agent (UCA) in a service, from a Service Component Architecture (SCA) service, from a web service that you create, or from a message that you post to the JMS Listener. If you want to create web services to initiate inbound requests from external systems, see Publishing IBM Business Process Manager web services. If you want to post a message to the JMS Listener, the Event Manager has a defined XML message structure that it must receive from an external system. For more information about the required message structure, see Posting a message to IBM Business Process Manager Event Manager. Outgoing messages can be received by a message event in a process, can be sent to call an external service, or can be received by the start event in another process or processes. To learn how to configure message events to send messages, see Using intermediate message events and message end events to send messages. You can include the following types of message events in your BPDs: Table 1. Available types of message events Event type Start event

Implementation Message that is configured to receive (Start events can only receive messages)

198

When to use Use to model the start of a process if you want an incoming message event to kick off the process. A BPD can include more than one start message event.Use as the start event for an event subprocess when you want the event subprocess to be triggered upon receipt of a message.

Intermediate event

Intermediate event

End event

Message that is configured Use to receive a message to receive event. Intermediate events can be attached to activities within your BPDs or they can be included in the process flow, which is connected with sequence flows. An intermediate event that is attached to an activity, rather than the swimlane, is known as a boundary event. Boundary events can optionally either interrupt and complete the activity, or be triggered repeatedly. Message that is configured Use to send a message to send event. Intermediate events can be included in the process flow, which is connected with sequence flows. Message that is configured Use to send a message to send (End events can event at the end of a path. only send messages)

When you create a message event, you can cut and paste or copy and paste that message event within the same BPD or from one BPD into another BPD. A message can cause a process instance to be created, and can be received by a running process that contains one or more appropriate message events. Before you include any type of message event that uses an undercover agent as the triggering mechanism, you should be aware of the following: - You can configure message events to consume messages. If you do, when a message is delivered to a running process, the message is consumed by the first message event in the BPD that can accept it (as determined by the undercover agent that is attached to the message event). When a message is consumed, it will not be processed again by that message event, or any other message event in the BPD instance that can accept it, should the execution of the BPD instance loop back and reach the same message event(s). If a new instance of the message is delivered to the process instance, this message is available for consumption again and is accepted by the message event. - Message events can be used to enable roll-forward scenarios in which the same message needs to be passed through multiple steps until it reaches the appropriate step in the process where it is to be consumed. To enable rolling a message forward through multiple message events, enable the Consume Message option only for the last message event in the chain of roll-forward message events. You can also use conditions to further control message consumption. - Occasionally, you might need to set conditions on the processing of incoming messages. If the condition that you specify evaluates to true, the message is accepted and processing continues-otherwise, it is stopped. Because the message 199

condition is evaluated before the message values can be passed to the input variables of the process definition, the message values are passed to the condition in a special namespace, tw.message. If the message condition evaluates to true, the values are passed from the tw.message namespace to the BPD input variables. - Using start message events If you want a process or event subprocess to start when a message is received, use a Start Message Event in your business process definition (BPD) or inside your event subprocess. - Using intermediate and boundary message events to receive messages You can include an intermediate message event in your business process definition (BPD) when you want to model a message event that is received during execution of a process. When the process execution reaches an intermediate message event, if a matching message is stored in the system, it is passed to the message event, otherwise, further execution along that path is blocked until an incoming message arrives that matches. - Using intermediate message events and message end events to send messages You can include an intermediate message event in your business process definition (BPD) when you want to model a message event that is sent during execution of a process, or a message end event when you want to send a message at an end of a path. - Setting the target for a UCA message event While you are configuring an undercover agent (UCA) message event in a business process definition (BPD) or configuring an Invoke UCA step in a service to use a message event, you can exercise some control over which snapshots use the event. You can override the default target by selecting a check box in the implementation settings for the UCA that carries the event. - Using message end events You can use a message end event when you want to send a message at an end of a path. Parent topic:Modeling events Related information: Modeling event subprocesses

200

Using start message events If you want a process or event subprocess to start when a message is received, use a Start Message Event in your business process definition (BPD) or inside your event subprocess. Incoming messages can originate from a message event in a process, from starting an undercover agent (UCA) in a service, from a Service Component Architecture (SCA) service, from a web service that you create, or from a message that you post to the JMS Listener.

Before you begin To perform this task, you must be in the IBM® Process Designer desktop editor.

About this task The general information that applies to all types of message events are covered in Modeling message events .When modeling start message events that use a UCA for the triggering mechanism, be aware of the following: - When a message is received by a start message event (specifying that an incoming message is to start a process at run time), a new instance of the process is created and a unique BPD instance ID is assigned to it. - If you use multiple start message events in a single BPD, use a separate undercover agent for each. If you use the same undercover agent for multiple start message events, IBM BPM instantiates multiple instances of the BPD. For example, you might want an employee on-boarding process to start when a record for each new employee is created in your HR system. When the record is created, the system sends an event to IBM Business Process Manager. IBM BPM captures the event and starts the follow-on steps for each new employee such as setting up the necessary space and computer equipment, requesting and creating a security badge.

Procedure 1. Open the Process Designer desktop editor. 2. Open a BPD or drill into an event subprocess, then drag a Start Event component from the palette onto the diagram. 3. On the Properties tab, click Implementation. 4. In the Start Event Details section, select the start event type Message. 5. If the start event is part of an event subprocess, the Start Event Details section shows the following options. A. If receiving and processing the message causes completion of the parent process, make sure that the Interrupt Parent Process option is selected, which is the default setting. When this option is selected, when the subprocess reaches its end, the parent instance is completed. Otherwise, clear the selection so that the parent process is not interrupted or completed when the message is received.

201

B. If Interrupt Parent Process is not selected, the Repeatable option is available. If the start message event can be triggered more than once, select the Repeatable option so that the subprocess can receive multiple messages. 6. To use UCA for triggering a start message event, complete the following actions in the Message Trigger section. A. For Triggering Mechanism, select UCA. B. To select an existing undercover agent, click Select next to the Attached Message UCA field. C. To create an undercover agent, click New. See Undercover agents. D. In the Condition text box, type a JavaScript expression if you want to define conditions under which the message event is processed.If you do specify a condition and the condition evaluates to true, the message is accepted and processing continues. If the condition evaluates to false, processing stops. In most cases, special message conditions are not necessary because you should implement each message event with a separate undercover agent. E. If you want the incoming message to be consumed after it is received by the message event, enable Consume Message. Refer to the bulleted list in Modeling message events to learn more about message consumption. F. The Durable Subscription check box is not available for start message events, only for intermediate message events as described in the following section. Important: The sender and receiver of the message must both use the same undercover agent. For example, if the sender of the message is a message end event in another BPD, then select the same undercover agent for both the receiving intermediate event and the sending message end event in the other BPD. Tip: UCAs must have a schedule type of On Event to function as a message trigger. Plus, the service that is attached to the selected undercover agent must have one or more input variables so that it can pass and correlate information from the event. 7. To use an SCA service for triggering a start message event, complete the following actions in the Message Trigger section. A. For Triggering Mechanism, select SCA Service. B. For Message Object Type, click Select to select a business object (BO) type, click New to define a new BO type, or leave it to be set automatically when you select a service definition. The business object type that you select determines the output parameters of the start message event. The message object type must be a complex type. C. For Service Identifier, a default value is provided, based on the name of the event, as shown in the BPD diagram. If you want, you can either specify a different service identifier name, or select one from the drop-down list of services that match the selected message object type. If you enter a name, it is restricted to using the NMToken character set. - If you selected an existing service definition and the message object type was not set, the message object type is updated to match the service definition. - The service identifier is used with the BPD name to generate a unique SCA service for this event point. The generated service interface name is displayed. 202

- If you selected an existing service definition, the associated events are added to the list of events that the definition includes. - To restore the default value, click the X (delete) icon. - If you specify the same SCA identifier for multiple message events, any changes to the service identifier or message object type affect all the events that provide the service. Making such changes can break data mappings for the events. Tip: If your BPD includes more than one start message, each one should use a different SCA service identifier. Otherwise, if multiple start message events specify the same SCA service identifier, the start event that receives the start message is selected arbitrarily.If you specify the same SCA identifier for multiple message events, the service interface can trigger multiple events in the BPD. However, each incoming message is received by only one of the events. Which event receives the message, or whether it is stored for future delivery, depends on whether a correlating process instance is found, and if so, which compatible message events are in the waiting state. For details of the semantics, see Using Service Component Architecture to interact with processes. Important: It is possible to define unintentionally the same service identifier on multiple events. For example, if different events have identical names (which is shown as an error on the General tab), or if different service identifiers map onto identical NMToken strings. If such a naming clash happens, you can break the unintended polymorphism by renaming the duplicate event names and then click X (delete) to restore the default service identifier name. 8. Specify the correlation and output mapping. A. On the Properties tab, click Data Mapping. B. Open the Correlation and Output Mapping section. C. Select the output variable that you want to use to for correlation. The value that is assigned to it ensures that the parameter values of the runtime message are passed to the correct BPD instance. The variable that is selected for correlation is identified by an assignment symbol ( ). This correlation ensures that the parameter values of the runtime message are passed to the correct BPD instance. - For undercover agents that are implemented using a complex variable rather than a service, you can select the complex variable or the top-level child properties of the variable for mapping or correlation. If you use SCA, you must select a variable that is marked as a process instance identifier that ensures that the message is passed to the correct BPD instance based on the value of that variable. D. Map each output variable to a local variable in the BPD. For each variable, click the variable selector icon to map each output variable to be passed into a local variable in the BPD. For example, if the start message event starts an instance of an on-boarding process when an employee record is created in your HR system, you can map the employee information from the undercover agent to a local variable in the BPD. 203

If your start message event is inside an event subprocess, you must select a variable to be used for correlating process instances. Correlation allows IBM BPM to identify the process instance that the message is meant for. For example, an employee number might be used to uniquely identify an instance of an on-boarding process. Selecting this variable for correlation ensures that when the data related to a specific employee number is passed to the event subprocess, the appropriate instance of the on-boarding process is found. Parent topic:Modeling message events Related information: Using Service Component Architecture to interact with processes

204

Using intermediate and boundary message events to receive messages You can include an intermediate message event in your business process definition (BPD) when you want to model a message event that is received during execution of a process. When the process execution reaches an intermediate message event, if a matching message is stored in the system, it is passed to the message event, otherwise, further execution along that path is blocked until an incoming message arrives that matches. Intermediate message events can be attached to activities within your BPDs or they can be included in the process flow, which is connected with sequence flows. Drag an intermediate message event onto the swimlane to create an intermediate message event. If you drag an intermediate message event onto an activity, it becomes a boundary message event. You can change either existing message event type to the other type by dragging it to or from the swimlane or activity.Tip: When you add message events in a BPD, be aware of the general information in Modeling message events that applies to all types of message events.

Before you begin To perform this task, you must be in the IBM® Process Designer desktop editor.

About this task For a receiving intermediate message event, you can use an undercover agent (UCA) for the message triggering mechanism. You can also use a Service Component Architecture (SCA) service as the triggering mechanism. Tip: To build a sample inbound integration that includes an intermediate message event included in the process flow, which is connected with sequence lines, see Building a sample inbound integration.

Procedure 1. Open the Process Designer desktop editor. 2. Open a BPD and drag an Intermediate Message Event component from the palette onto the BPD diagram. It can be dragged to the swimlane or attached to an activity. When the event is attached to an activity, the event is known as a boundary event and it is included in the outline of the activity. 3. On the Properties tab, click Implementation. 4. Select the event type Message. A. If you dragged the Intermediate Message Event component onto the BPD diagram, in the Intermediate Event Details section, select the intermediate event type Message. B. If you dragged the Intermediate Message Event component onto an activity, in the Boundary Event Details section, select the intermediate event type

205

Message. 5. If the intermediate message event is a boundary event, use the Boundary Event Details section to specify its behavior: A. If receiving the message signals completion of the activity, make sure that the Interrupt Activity option is selected, which is the default setting. Otherwise, clear the selection, so that the activity is not interrupted and completed when the message is received. B. If Interrupt Activity is not selected, the Repeatable option is available. If the boundary message event can be triggered more than once, select the Repeatable option so that the attached activity can receive multiple messages. 6. To use a UCA for triggering an intermediate message event, complete the following actions in the Message Trigger section. A. For Triggering Mechanism, select UCA. B. To select an existing undercover agent, click Select next to the Attached Message UCA field. C. To create an undercover agent, click New. See Undercover agents. D. In the Condition text box, type a JavaScript expression if you want to define conditions under which the message event is processed.If you do specify a condition and the condition evaluates to true, the message is accepted and processing continues. If the condition evaluates to false, processing stops. In most cases, special message conditions are not necessary because you should implement each message event with a separate undercover agent. E. If you want the incoming message to be consumed after it is received by the message event, enable Consume Message. Refer to the bulleted list in Modeling message events to learn more about message consumption. F. To allow the message event to receive an incoming message that arrives before a process is at a point where the event can accept the message, select Durable Subscription. The durable subscription causes the message to be stored until the message event is reached. Only the most recently received message is stored. Tip: If you occasionally use inbound messages and undercover agents, consider using durable subscription events. When Durable Subscription is selected, incoming messages are persisted in the database. The durable messages accumulate, even if you select the check box to make them consumable. Periodically use the BPMDeleteDurableMessages command for deleting durable subscription events. Important: The sender and receiver of the message must both use the same undercover agent. For example, if the sender of the message is a message end event in another BPD, then select the same undercover agent for both the receiving intermediate event and the sending message end event in the other BPD. Tip: Undercover agents must have a schedule type of On Event to function as a message trigger. Plus, the service that is attached to the selected undercover agent must have one or more input variables so that it can pass and correlate information from the event. 7. To use an SCA service for triggering an intermediate message event, complete the following actions in the Message Trigger section. A. For Triggering Mechanism, select SCA Service. 206

B. For Message Object Type, click Select to select a business object (BO) type, click New to define a new BO type, or leave it to be set automatically when you select a service definition. The business object type that you select determines the output parameters of the intermediate message event. The message object type must be a complex type. C. For Service Identifier, a default value is provided, based on the name of the event, as shown in the BPD diagram. If you want, you can either specify a different service identifier name, or select one from the drop-down list of services that match the selected message object type. If you enter a name, it is restricted to using the NMToken character set. - If you selected an existing service definition and the message object type was not set, the message object type is updated to match the service definition. - The service identifier is used with the BPD name to generate a unique SCA service for this event point. The generated service interface name is displayed. - If you selected an existing service definition, the associated events are added to the list of events that the definition includes. - If you specify the same SCA identifier for multiple message events, any changes to the service identifier or message object type affect all the events that provide the service. Making such changes can break data mappings for the events. - To restore the default value, click the X (delete) icon. Tip:If you specify the same SCA identifier for multiple message events, the service interface can trigger multiple events in the BPD. However, each incoming message is received by only one of the events. Which event receives the message, or whether it is stored for future delivery, depends on whether a correlating process instance is found, and if so, which compatible message events are in the waiting state. For details of the semantics, see Using Service Component Architecture to interact with processes. Important: It is possible to define unintentionally the same service identifier on multiple events. For example, if different events have identical names (which is shown as an error on the General tab), or if different service identifiers map onto identical NMToken strings. If such a naming clash happens, you can break the unintended polymorphism by renaming the duplicate event names and then click X (delete) to restore the default service identifier name. 8. Specify the correlation and output mapping. A. On the Properties tab, click Data Mapping. B. Open the Correlation and Output Mapping section. C. Select the output variable that you want to use to for correlation. The value that is assigned to it ensures that the parameter values of the runtime message are passed to the correct BPD instance. The variable that is selected for correlation is identified by an assignment symbol ( ). This correlation ensures that the parameter values of the runtime message are passed to the correct BPD instance. - For undercover agents that are implemented using a complex variable rather than a service, you can select the complex variable or the top-level child properties of the variable for mapping or correlation.

207

-

If you use SCA, you must select a variable that is marked as a process instance identifier that ensures that the message is passed to the correct BPD instance based on the value of that variable. D. Map each output variable to a local variable in the BPD. For each variable, click the variable selector icon to map each output variable to a local variable in the BPD. Parent topic:Modeling message events Related information: BPMProcessInstancesCleanup command BPMDeleteDurableMessages command Creating and configuring an undercover agent for a message event Attaching the undercover agent to the message event Using Service Component Architecture to interact with processes

208

Using intermediate message events and message end events to send messages You can include an intermediate message event in your business process definition (BPD) when you want to model a message event that is sent during execution of a process, or a message end event when you want to send a message at an end of a path. For example, you might want to call an external service or to send a message to be received by the start event in another process or processes. Message events can be included in the process flow, which is connected with sequence lines. Intermediate message events have both incoming and outgoing sequence flows, while message end events have only incoming sequence flows. Tip: When you add message events in a BPD, you should be aware of the general information in Modeling message events that applies to all types of message events.

Before you begin To perform this task, you must be in the IBM® Process Designer desktop editor.

Procedure 1. Open the Process Designer desktop editor. 2. Open a BPD and drag an intermediate or end event from the palette onto the BPD diagram. 3. In the text box that displays over the event, type a name for the event. 4. Use the Sequence Flow tool to connect the event as needed. 5. In the diagram, select the new event. 6. On the Properties tab, click Implementation. The default implementation for intermediate events that are included in the process flow is Message. If you are creating a message end event, select Message end event as the implementation type. 7. If you are creating an intermediate message event, select Sending from the available message types in the drop-down list. By default, all message end events are sending message end events. 8. In the Message Trigger section, complete one of the following actions. - To select an existing undercover agent, click Select next to the Attached Message UCA field. - To create an undercover agent, click New. See Undercover agents. Important: The sender and receiver of the message must both use the same undercover agent. For example, if the sender of the message is a message end event in another BPD, then select the same undercover agent for both the receiving intermediate event and the sending message end event in the other BPD. Tip: Undercover agents must have a schedule type of On Event to function as a message trigger. Plus, the service that is attached to the selected undercover agent must have one or more input variables so that it can pass and correlate

209

information from the event. 9. If you created an end event, specify the input mapping. A. On the Properties tab, click Data Mapping. B. Open the Input section. C. Map each input variable to a local variable in the BPD. For each variable, select it then complete one of the following actions. - Click the variable selector icon to map each input variable to a local variable in the BPD. - Enter a literal value or the name of a local variable. - To use the default value from the variable, click Use default. When you enable this check box, the variable selector icon is disabled. Parent topic:Modeling message events Related information: BPMProcessInstancesCleanup command BPMDeleteDurableMessages command Creating and configuring an undercover agent for a message event Attaching the undercover agent to the message event

210

Setting the target for a UCA message event While you are configuring an undercover agent (UCA) message event in a business process definition (BPD) or configuring an Invoke UCA step in a service to use a message event, you can exercise some control over which snapshots use the event. You can override the default target by selecting a check box in the implementation settings for the UCA that carries the event. You can include an intermediate message event in your BPD when you want to model a message event that is sent or received while a process is running, or you can use a start event to receive a message event or use an end event to send a message event. The default behavior for intermediate incoming message events is that they are received by all snapshots in all process applications that refer to the undercover agent and that have event message properties that match the correlation values. For start message events, the default behavior is that they are used on the tip in Process Center and in the default snapshot on IBM® Process Server. To change that default behavior, select the check box labeled Target the snapshot of the installed process application that contains this BPD or Target the snapshot of the installed process application that contains this service. (The label depends on your context.) You encounter the check box when you are configuring the undercover agent for a message event. If you select the check box, at run time start message events are targeted in the same snapshot of the process application that contains the BPD or the service that sends the message event. If the BPD or the service of the sending message event is in a toolkit, the snapshot of the process application (which is the root container) is used. When the check box is selected, you are limiting the responding listener to the start message event and to the intermediate incoming message events in that specific process application snapshot. Parent topic:Modeling message events Related information: Designating default snapshots Adding a message event to a BPD Attaching the undercover agent to the message event Using intermediate message events and message end events to send messages Creating and configuring an undercover agent for a message event

211

Using message end events You can use a message end event when you want to send a message at an end of a path.

Before you begin To perform this task, you must be in the IBM® Process Designer desktop editor.

About this task For example, you might want to send a message to be received by the Start event in another process or processes. When including message end events in a business process definition (BPD), you should be aware of the general information that applies to all types of message events covered in Modeling message events.

Procedure 1. Open the Process Designer desktop editor. 2. Open a BPD and drag an end event from the palette onto the diagram. 3. In the text box that appears over the event, type a name for the event. 4. Click the Implementation option in the properties. 5. Click the drop-down list and select Message from the end event types. By default, message end events can only send messages. 6. In the Message Trigger section, click Select next to Attached UCA to select an existing undercover agent.To create an undercover agent, click New. See Undercover agents. Undercover agents must have a schedule type of On Event to function as a message trigger. Plus, the service attached to the selected undercover agent must have one or more input variables so that it can pass and correlate information from the event. Note: Ensure that the sender and receiver of the message both use the same undercover agent. For example, if the receiver of the message is an message intermediate event in another BPD, then select the same undercover agent for both the sending message end event and the receiving intermediate event in the other BPD. 7. Click the Data Mapping option in the properties. 8. In the Input section, click the variable selector icon on the right side of each field to map each undercover agent output variable to a local variable in the BPD. Click the Use default check box if you want to use a default value from the attached undercover agent for a particular variable. When you enable this check box, the variable selector icon is disabled. Parent topic:Modeling message events

212

Enabling users to perform ad hoc actions (deprecated) Use an ad hoc event when you need to include ad hoc actions that can be run at any time during process execution. Important: Ad hoc actions are deprecated in version 8.5.5.0, instead use Creating an unstructured (ad hoc) activity. If you want to enable end users to perform an ad hoc action during the execution of another process, you can do so by using a start ad hoc event in your BPD. For example, you may want to enable end users to cancel an order, determine the status of an order, or perform some other ad hoc function during the normal processing of an order. Because an ad hoc action is run in the context of the regular process instance, it has access to all the data of the regular process instance and can also manipulate the flow of the regular process instance, depending on the logic that you include.Important: Process Portal users who perform ad hoc actions must be assigned to the security group that is configured for the ACTION_INJECT_TOKEN policy. Modify the security properties of the BPMActionPolicy configuration object as described in Security configuration properties.

- Building a sample ad hoc action (deprecated) This example shows how to model an ad hoc action that enables users to view the contents of a requisition at any time during normal processing of the requisition. - Testing a sample ad hoc action (deprecated) Use IBM® Process Designer to test the sample ad hoc action. Parent topic:Modeling events Related information: Configuring access to Process Portal action policies Deprecated: Defining ad hoc actions

213

Building a sample ad hoc action (deprecated) This example shows how to model an ad hoc action that enables users to view the contents of a requisition at any time during normal processing of the requisition.

Before you begin To perform this task, you must be in the IBM® Process Designer desktop editor.

About this task For the following example, you can use the Standard HR Open New Position business process definition (BPD) included in the Hiring Sample process application. (If you do not see the Hiring Sample process application in your list of applications in the Process Center Console, ask your IBM Business Process Manager administrator to give you access.) To do so, clone a snapshot of the Hiring Sample process application so that your changes do not affect other users of IBM Process Designer.

Procedure 1. 2. 3. 4.

Open the Process Designer desktop editor. Open a BPD in the Designer view and click the Diagram tab. Drag a swimlane from the palette to the diagram. Right-click the new lane and select Move Lane Down until the new lane is the last lane in the BPD (below the System lane). 5. Click the new lane in the diagram (named Untitled 1 by default) and in the Name field in the properties, type Ad hoc event . 6. Drag a start event from the palette onto the BPD diagram so that it is positioned in the new Ad hoc event lane. 7. In the text box that displays over the start event , type Show Requisition Data for the event name. 8. Click the Implementation tab in the Properties view and select Ad Hoc from the available start event types. If you wanted to restrict the users who can perform the action, you could also associate a specific team with the swimlane and then in the Event Visibility section specify that the event visibility is restricted by swimlane. 9. Drag an activity from the palette into the Ad hoc event lane. 10. In the text box that displays over the user task,, type Show Data for the user task name. 11. Drag an end event from the palette onto the BPD diagram so that it is positioned after the Show Data activity in the Ad hoc event lane and optionally name the end event. 12. Using the Sequence Flow tool, connect the Show Requisition Data start event, the Show Data activity, and the end event on the BPD diagram. 13. Right-click the Show Data activity and select Activity Wizard from the list of options.

214

14. In the Activity Wizard - Setup Activity window, make the following selections: Table 1. Recommended selections in the Activity Wizard - Setup Activity window Option Activity Type Service Selection

Selection User Task Select the Create a New Service or Process option.

In the Name field, type Show Data for the new service. (For this example, name the new Human service the same as the corresponding activity in the BPD.) 15. In the Activity Wizard - Setup Activity window, click Next. 16. In the Activity Wizard - Parameters window, choose the process variables from the regular process to use as input and output for the new service for the ad hoc process.For the private variable named requisition, leave the Input field set to true and change the Output field to false. These settings reflect the fact that our sample ad hoc event simply displays the requisition data and does not pass back modified data. For other variables, click to change the setting from true to false under the Input and Output field. Click Finish. The new service is created and attached to the activity. The new service includes a single Coach. 17. Double-click the Show Data activity in the Ad hoc event lane in the BPD.The new service opens and you can see the service diagram. 18. Click the Coaches tab and then click the listed Coach to see its controls. Because we used the Activity Wizard, the Coach includes a form element for each of the parameters in the requisition variable. 19. Save your work and then follow the instructions in Deprecated: Testing a sample ad hoc action. Parent topic:Enabling users to perform ad hoc actions (deprecated) Related information: Hiring tutorial Configuring access to Process Portal action policies

215

Testing a sample ad hoc action (deprecated) Use IBM® Process Designer to test the sample ad hoc action.

Before you begin To perform this task, you must be in the IBM Process Designer desktop editor. Before you can test the sample ad hoc action, you must have a business process definition (BPD) that contains an ad hoc event and at least one task connected by sequence flow. For example, you can modify the Hiring Sample BPD to contain an ad hoc action as described in Deprecated: Building a sample ad hoc action.

Procedure 1. 2. 3. 4.

Open the Process Designer desktop editor. Open a BPD in the Designer view. Click the Run icon in the upper right corner of the BPD diagram. IBM Process Designer switches to the Inspector where you should see a new Submit requisition task in the task list. 5. Open IBM Process Portal and log in as a member of one of the teams who receive and can complete the tasks generated by the activities in the BPD. 6. Run the Submit requisition task displayed in your Open Tasks view in IBM Process Portal. 7. Fill out the Job Requisition information, click Next, and then Submit on the Confirm Job Position form. 8. When the next task for the process instance (Approve/reject requisition) displays in your Open Tasks view in IBM Process Portal, click the instance name or task subject to open the details page. Note: If the task does not display, reload the browser page. 9. Click the Actions menu in the toolbar, and select the name of the ad hoc action. (The name of the action is the name that you assign the ad hoc event that initiates the user task in the BPD diagram in IBM Process Designer. If you are using the modified Hiring Sample, the name is Show Requisition Data. )IBM BPM generates a new task called Show Data, which is displayed in your Open Tasks view. 10. Run the Show Data task. If you receive an information message about claiming the new task, click Claim Task. IBM BPM displays the data that you entered in step 5. 11. Click OK.Now you can continue with normal processing by completing the next task in the process instance, Approve/reject requisition. You can invoke the ad hoc action again, after completion of the Approve/reject requisition task, to see whether the requisition has been approved.

What to do next The ad hoc event and user task that you added to the BPD diagram enables you to view the requisition information at any time during running of the regular process.

Parent topic:Enabling users to perform ad hoc actions (deprecated)

216

Related information: Getting started with Process Portal Configuring access to Process Portal action policies

217

Modeling event gateways Use an event gateway to model a point in the process execution where only one of several paths can be followed, depending on events that occur.

Before you begin To perform this task, you must be in the IBM® Process Designer desktop editor.

About this task An event gateway represents a branching point in a process execution where only one of several paths can be followed, depending on events that occur. A specific event, such as the receipt of a message or timer event, determines the path that will be taken. The event gateway represents a single point of behavior that is spread out across multiple process components connected by sequence flow. The following types of events can directly follow an event gateway (connected by a single sequence flow): - Intermediate message event (receiving) - Intermediate timer event When creating an event gateway, you must connect at least two intermediate events to the gateway. And, when connected to an event gateway, an intermediate event is not allowed to have additional incoming sequence flow.

Procedure 1. Open the Process Designer desktop editor. 2. Open a business process definition (BPD). 3. Drag a gateway from the palette to the process diagram. 4. In the text box that displays over the gateway, type a name for the gateway. 5. Click the General option in the properties. 6. In the Behavior section of the general properties, click the drop-down list and select Event Gateway from the available gateway types. To streamline configuration of an event gateway, IBM Process Designer automatically adds an intermediate message event (receiving) and an intermediate timer event to the process diagram. These intermediate events are grouped with the event gateway in the process diagram. 7. Add any additional events required by the gateway configuration by dragging them from the palette to the event gateway group in the process diagram. Only intermediate message events and intermediate timer events are allowed. The minimum number of events is two, and you can add as many as you require. 8. Click an event in the group and then select the Implementation option in the properties. A. To configure an intermediate message event, follow the steps in Using intermediate and boundary message events to receive messages. B. To configure an intermediate timer event, follow the steps in Modeling timer events.

218

Parent topic:Modeling events

219

Handling errors using error events When you design a business process definition (BPD) or a service, provide logic to recover from possible errors that might be generated in the runtime application. When you develop an application in IBM® BPM, build error handling into BPDs and services to do the following things: - To detect errors. - To specify how errors are thrown and caught in your runtime environment. - To recover in a predictable manner. For example, if a BPD involves filling orders, an item might be out of stock during one instance of the BPD, which causes an error. Error handling that you build into the BPD could create notifications to replenish items that are out of stock. There are three types of error events: - Error end events in BPDs and services that throw errors - Error intermediate events in BPDs and services that catch errors - Error start events in BPD event subprocesses that catch errors You can assign error codes and error data to errors that are thrown by the error end events. To catch errors using error intermediate events, select an error code from a list of previously defined errors and map the error data to a variable. The error intermediate events are boundary events, which are intermediate events that are attached to the boundary of an activity. Each boundary event can be triggered only while the activity is running, interrupting the activity. From the BPD diagram or a service diagram in Process Designer, you can use an error intermediate event that is attached to the boundary of an active to catch specific errors and error data from a linked process, a subprocess, or a service. Another way to catch errors is by using error intermediate events in services that catch all errors. When building services, you can attach an error intermediate event to the boundary of a step to catch all errors for the step, and you can use an error intermediate event as part of the service flow to catch all errors that are raised by steps of the service flow that are not handled by an error intermediate event at the boundary of the step. You also can catch errors using error event subprocesses in BPDs. In the subprocess, you use an error start event that catches errors if the start event is triggered. However you decide to catch errors, designate the error behavior for the events on the Properties tab in your diagram. Under Implementation, go to the Error Properties section to designate the following error handling behavior: - Catch all errors or specific errors. To catch specific errors, you can select the error code, map the error data, or both, as described in the following bullets. - Filter the specific errors that are caught by selecting an error code from a list of all thrown errors for the linked process, subprocess, or service. - Map the error data into a variable by selecting an error mapping variable that was previously defined on the Variables tab. Important: If the error code has changed, make sure to select the variable again so that it is mapped properly. If there are multiple error events defined to catch errors for an error that is thrown in

220

a linked process, subprocess, or service, the catching event is determined by the precedence rules in the order that they are listed in the Error event components table. Errors are caught in the following order in your runtime environment: 1. The boundary events catch errors that are raised by the attached activity, as described in the following table. 2. If there is no error boundary event that handles the error, and a subprocess is in a BPD or in an unattached intermediate error event in a service, errors are caught in the error event subprocesses, as described in the following table. 3. If there is no error event subprocess that handles the error in an event subprocess, linked process, or service, errors are propagated to the next level.

Table 1. Error event components Specify error code and error data error code error data neither code nor error data or the Catch All Errors option on error properties

Errors caught Only errors with the same code and data type Errors with the same code, unless they are already caught by an event, as specified by the preceding rule Errors with the same data type, unless they are already caught by an event, as specified by the preceding rules All errors that are not already caught by an event, as specified by the preceding rules

Note: Multiple events that are defined in the same context and with the same constraints cause nondeterministic runtime behavior. Specifying the variable name in the mapping controls the filtering by error data type. If the type of the variable and the type of the error data that is displayed on the Properties tab do not match, the variable type determines the behavior. - Handling errors in BPDs When modeling error handling as part of your business process definitions (BPDs), you can catch errors using error intermediate events or event subprocesses, and you can throw errors using error end events. - Handling errors in services For services, you can use error intermediate events to catch errors, and you can use error end events to throw errors. - Error events in models from V7.5.x and earlier If you have Process Designer models from V7.5.x or earlier that use error events, the earlier error handling behavior is still available. Parent topic:Modeling events

221

222

Handling errors in BPDs When modeling error handling as part of your business process definitions (BPDs), you can catch errors using error intermediate events or event subprocesses, and you can throw errors using error end events. Table 1. Usage of error events in business process definitions BPD event

Description Catches specified errors or all error intermediate event at the errorsProvides error handling logic for boundary of an activity (error boundary errors raised by the activity that it is event) attached to error event subprocess that starts with an Catches specified or all errorsProvides error handling logic for errors raised by error start event activities of the BPD, subprocess, or event subprocess that directly contains the error event subprocess Throws an error error end event

Catching errors using error intermediate events For BPDs, you can attach an error intermediate event to an activity and connect that event to an error handling flow or activity. The attached error event is known as a error boundary event. To determine whether to use error immediate events, consider the following points: - If an error occurs while a process is running an activity with an attached error event at the boundary, the process flows along the sequence line that is attached to the error event. Errors are handled in the flow and then proceed with the normal processing. - Error intermediate events must be attached to an activity. - You can have multiple error events for an activity, but only one catches the error. - Consider specifying the error data to catch specific errors, filtering on the error code for the types of errors that are caught, and mapping to a variable after the errors are caught. When all errors are caught, or if only an error code is specified, the error data is captured in an XMLElement in the tw.system.step.error variable.

Catching errors using error event subprocesses An event subprocess is a specialized type of subprocess that is not part of the normal sequence flow of its parent process. An error event subprocess is an event subprocess that contains an error start event. The event subprocess is not connected by sequence flow and runs only if the start event in the event subprocess is triggered. You can use error event subprocesses to handle errors in your BPD. To determine whether to use error event subprocesses, consider the following points: - Define a readable process by locating the error event in the event subprocess instead of defining it in the process. 223

- To reuse the error-handling flow for multiple tasks in your process, use event subprocesses. To reuse an error-handling flow using attached events, you must attach an intermediate event for each of the tasks and then connect those events to the error-handling flow. - Define data objects that you can access only from within the event subprocess. You can define only those data objects that belong to a subprocess. The parent process is not cluttered with unnecessary variables. For more information about event subprocesses, see Modeling event subprocesses .

Throwing errors You can use an error end event in your BPD to specify an error code and map to an error type on errors thrown from the flow of a BPD or a service. When working with either error events or event subprocesses, think about whether errors can be handled immediately, and normal processing can continue, or if another error can be thrown at another level. Then implement error handling from the bottom up. In other cases, it might be more efficient and readable if subprocess can be reused. Build each linked process and service so that errors can be captured and corrected. If a correction is not possible at the lowest level of the implementation, you can allow the error to move up a level by not including an error event or include an error event to rethrow the error to the calling service or process, as shown in the following section. For example, to ensure that any errors that might occur during process run time are captured, you can create a high-level BPD that includes an activity to call the main process as a linked process and then one additional activity with an underlying service to implement error handling as shown in the following image:

This type of design ensures that errors thrown from underlying processes and services are propagated up and handled appropriately.

Parent topic:Handling errors using error events

224

Handling errors in services For services, you can use error intermediate events to catch errors, and you can use error end events to throw errors. Table 1. Usage of error events in services Service event error intermediate event attached to the boundary of a step (error boundary event) error intermediate event service flow

error end event

Description Catches errors from the step

as part of the Catches all errors raised by steps of the service flow that are not handled by an error intermediate event at the boundary of a step. This event can have only outbound links. Throws an error and ends the processing of this service. You might, for example, use an error end event when you want a particular result from a Coach to end a human service.

To determine whether to use error events in your services, consider the following points: - You must attach error intermediate events to steps in your service. The attached error event is known as a error boundary event. - Include error intermediate events in the service flow so that they can act as global error handlers in the service. - Determine whether errors can be handled immediately, and normal processing can be continue, or if another error can be thrown at another level. Then implement error handling from the bottom up. - Use an error end event to throw a specific error. You can specify an error code and error data for the error. - Consider specifying the error data to catch specific errors. For example, you could filter on the error code for the types of errors that are caught and map the error code to a variable after the errors are caught. When all errors are caught, or if only an error code is specified, the error data is captured in an XMLElement in the tw.system.error variable.

Using error intermediate events in the service flow The use of error intermediate events in a service flow offers several options in error handling, but it must be done carefully to prevent unexpected behaviour. An error intermediate event in the service flow can act as a global error handler in the service. It catches errors that are not already handled by boundary error events. The error intermediate event cannot catch specific errors; it is a catchAll error event. It is meant for handling errors that can be handled within that very service flow. It is recommended that you not wire back into the normal flow. Instead, after the error handling, logic should be concluded with an end event. After the error handling you 225

might reenter the service and run the normal flow with corrected data. To handle errors in a service and wire back to the normal flow in the same service, use one or more error boundary events with specific errors and the catchAll options.

Note: An error intermediate event in the service flow also catches errors thrown through error end events of that service flow. Important: The error intermediate event can cause endless loops if follow-up activities after the event throw a runtime or a modeled error. The service engine prevents these loops. In some cases, it might be useful to model a loop with an intermediate error end event. To allow looping, add the following entry to the 100Custom.xml file: false



Changing this property will globally suppress the error loop detection of the service engine. Change this property only if all your models are free of endless error loops.

Parent topic:Handling errors using error events

226

Error events in models from V7.5.x and earlier If you have Process Designer models from V7.5.x or earlier that use error events, the earlier error handling behavior is still available. Models that were created in V7.5.x and earlier versions include the following errorhandling behavior: - Error intermediate events at the boundary of a step in services or at the boundary of an activity in a business process definition (BPD), subprocess, or event subprocess catch all errors. As of V8.0, you model this behavior using the Catch All Errors option, which is available on the Properties tab for a catching error event. In addition, you can refine your error handling by catching specific errors using the Catch Specific Errors option. - Error intermediate events in the flow of a BPD, subprocess, or event subprocess were allowed but had no effect on runtime behavior. You can delete these events. - Error end events in services, BPDs, subprocesses, or event subprocesses retain the same error throwing behavior: they can be caught only as part of an event that catches all errors. To use the extended error-handling capabilities, delete the old event and add a new event. To use the latest error-handling capabilities, you can move the models to V8.0. Open your application, look at the referenced system toolkits, click a toolkit, and select the menu option to upgrade it. Parent topic:Handling errors using error events

227

Using Service Component Architecture to interact with processes There are several ways to start and interact with business process definition (BPD) instances using Service Component Architecture (SCA). You can use receiving message events to create or interact with BPD instances. You can also use SCA to create a BPD instance without the use of a receiving message event. In that scenario, the inputs of the BPD and optionally its outputs define the service interface for the SCA interaction. To interact with receiving message events, you can use SCA as the triggering mechanism as an alternative to using undercover agents (UCA). A receiving message event can be a start message event, intermediate message event, boundary message event, or the start event of an event subprocess. The use of SCA as the triggering mechanism makes it possible to use instancebased correlation that always delivers the message to exactly one event of one instance. By contrast, correlation that is supported by undercover agent invocations permits multiple instances and events (of the same or different models) to receive the same message.

Supported interaction patterns that use receiving message events You can use SCA messages to invoke the following BPD event types. These interactions are one-way interactions. - Message Start Event - The start event causes a new instance of the BPD to be created. If your BPD includes more than one start event, each one should use a different SCA service identifier. Otherwise, if multiple start events specify the same SCA service identifier, the start event that receives the start message is selected arbitrarily. - Start Event of a Message Event Subprocess - The Start Event of a Message Event Subprocess requires correlation. A message that invokes a message event subprocess must be correlated with the BPD instance that then invokes the event subprocess. Optionally, this event type can be configured to be repeatable or to interrupt the parent process instance. - Intermediate Message Event - An intermediate message event requires correlation to ensure that the message triggers the intermediate message event that belongs to the correct BPD instance. - Boundary Message Event - A boundary message event is an intermediate message event that is attached to an activity. A boundary message event requires correlation to ensure that the message triggers the boundary message event that belongs to the correct BPD instance. Optionally, this event type can be configured to be repeatable or to interrupt the activity that the event is attached to.

228

Supported interaction patterns that use input and output variables The input and output variables of the BPD define the parameters of the SCA request message and SCA response message. They are used to store the parameter data of the request message and the response message that are exchanged by means of SCA. There are two interaction patterns: - One-way interface - You create a BPD instance using the one-way interface of the BPD. The message parameters are automatically assigned to the input variables when the BPD instance receives the SCA message. - Request-response interface - You create a BPD instance and upon the completion of the BPD, you receive a response message that uses the request/response interface of the BPD. The request message parameters are automatically assigned to the input variables when the BPD instance receives the SCA request message. The SCA response message is constructed from the output variables when the BPD instance ends. The one-way interface and the two-way interface are derived from the input and output variables. Both interfaces are available in IBM® Integration Designer for use as an SCA module.

Instance-based correlation If a request message must be received by an existing instance of a BPD, you must specify a correlation variable to identify the intended instance that receives the message. SCA message correlation requires that at least one of the BPD's variables is marked as being a process instance identifier. The correlation variable can be written to only once. The value that is assigned to the correlation variable must uniquely identify the instance. Normally, business data is assigned to a process instance identifier variable. For example, the correlation variable might be assigned an employee number from the start message. All messages that are intended for the same instance must include the same value for the correlation variable to identify the appropriate process instance. The value that is used to identify a process instance cannot be reused to identify a new instance until after the first instance is in the completed or terminated state, or the instance is deleted.Important: You must ensure that the process instance identifier variable is initialized before any message is sent for the instance. Because the correlation matching is only performed when the message arrives, if a message arrives before the process instance identifier variable is initialized, it can never match with a process instance, and can never trigger a receiving message event. If a message is posted before the a suitable message receive event is in a waiting state, the message is stored. The message will be received by the first matching message receive event that goes into the waiting state.

Defining a service that can trigger different events in a BPD In general, when receiving message events are used with SCA, the corresponding service interfaces of the BPD are derived from the message event's service identifier and message object type. 229

You can specify that the BPD exposes only one service, which is implemented by different receiving message events of the BPD. To do so, specify the same service identifier and message object type for different message events in the BPD. When a message is received, one of the receiving message events will process it. Which event receives the message depends on whether a correlating process instance is found, and if so, which event is active, or reached first. - If a process instance matches the instance identifier value in the message, then the following rules are applied: - If the instance has exactly one matching event (intermediate, boundary, or a start event for an event subprocess) that is in the waiting state, the matching event receives the message. - If the instance has multiple matching events that are in the waiting state, one of them is selected arbitrarily to receive the message. - If the instance does not have any matching event in the waiting state, the message is stored until an event that can receive the message becomes active. - If no process instance matches the instance identifier value in the message and there is a start process message event that matches the message type, a new instance of the BPD is created, and the start message event receives the message. Warning: It is possible to define unintentionally the same service interface for multiple events. For example, if different events have identical names (which is shown as an error on the General tab), or if different service identifiers map onto identical NMToken strings, then different events share the same service interface. If this naming conflict happens, you can break the naming conflict by renaming the duplicate event names and then restoring the default service identifier name.

Rules for instance migration To allow instance migration of BPDs that contain SCA message events and variables that are marked as process instance identifiers, you must conform to the rules for what cannot be changed or deleted when you create a new version of a BPD that is already deployed. The rules are described in Strategies for migrating instances.

Task overview To use SCA to interact with a BPD, you must complete the following actions: 1. Using Process Designer:You can either use the implicitly provided services of the BPD, or use the services that are provided for a receiving message event in which SCA is specified as the triggering mechanism. For the former you do not have to do anything, for the latter you must specify the corresponding receiving message events. A. If SCA messages interact with existing BPD instances, use instance-based correlation for the message event subprocess, intermediate receiving message events, or boundary message events. For that, you must mark one or more of the process variables as process instance identifiers. See Declaring variables for a BPD or a service in Process Designer. B. Ensure that the process variable that identifies a BPD instance is assigned a suitable value. The value must be assigned before any SCA message can 230

arrive for the instance. C. Optional: Add a start message event to your process. See Using start message events. D. If you want message event subprocesses or receiving message events in a process to be able to receive SCA messages: 1. Add intermediate receiving message events and boundary message events as necessary. See Using intermediate and boundary message events to receive messages. 2. Add a message event subprocess, with a corresponding start message event where required. See Using start message events. 3. For each receiving message event, as a part of the data mapping, select the variable that uniquely identifies each process instance. See Mapping input and output data for an activity or step. 2. Switch to using IBM Integration Designer, and complete the following actions: A. Drag the BPD onto the design canvas, and select which interfaces to include in the SCA import. See Creating an import to start a business process definition. B. In the assembly editor, you can use the SCA import to invoke and communicate with a BPD instance using SCA messages.

Parent topic:Modeling events

231

Undercover agents An undercover agent (UCA) is attached to a message event or a content event in a business process definition (BPD) and calls a service to handle the event. An undercover agent is started by an event. For example, when a message event is received from an external system, an undercover agent is needed to start the appropriate service in response to the message. Message events can originate from any of the following components: - BPDs (see Modeling message events) - web services that you create (see Publishing IBM Business Process Manager web services) - messages that you post to the JMS listener (see Posting a message to IBM Business Process Manager Event Manager) When an undercover agent runs, it starts an IBM® Business Process Manager service or a BPD in response to the event. When you include a message event or a content event in a BPD, you must attach an undercover agent to the event. For example, when a message event is received from an external system, an undercover agent is needed to trigger the message event in the BPD in response to the message. If you want to run the startBpdWithName application programming interface (API) to start a BPD instance inside an undercover agent, set the property to true in the 100Custom.xml file or another override file. Restart the product, and check the TeamworksConfiguration.running.xml file to ensure that the setting has the appropriate value. The property is set to false by default, and if you don't change it, you might have errors that prevent the BPD from starting. - Creating and configuring an undercover agent for a message event You can create an undercover agent (UCA) that invokes a particular service as the result of an incoming or an outgoing message event. - Creating and configuring an undercover agent for a scheduled message event You can create an undercover agent (UCA) that invokes a service as the result of a message event that occurs on a regular schedule. - Creating and configuring an undercover agent for a content event To obtain information about document or folder events on an Enterprise Content Management (ECM) server, you must create and configure a content undercover agent that works with your event subscription. A content undercover agent (UCA) is used to initiate a BPM Start or Intermediate event when specific content changes occur on an ECM server. It is conceptually similar to a message undercover agent, but it has a specialized Content marker to differentiate it from a Message marker. Parent topic:Modeling events Related information: Creating inbound integrations Creating an undercover agent

232

Attaching the undercover agent to the message event

233

Creating and configuring an undercover agent for a message event You can create an undercover agent (UCA) that invokes a particular service as the result of an incoming or an outgoing message event.

Before you begin To perform this task, you must be in the IBM® Process Designer desktop editor.

About this task See Building a sample inbound integration to learn how to build a sample integration that includes this type of undercover agent.

Procedure 1. Open the Process Designer desktop editor. 2. In the Designer view, click the plus (+) sign next to Implementation and then select Undercover Agent from the list. 3. In the New Undercover Agent window, enter the following information: - Name: Type a name for the new undercover agent. - Schedule Type: Select On Event from the drop-down list. - Click Finish. 4. In the Common section, you can type a description of the undercover agent in the Documentation text box. 5. In the Scheduler section, you can see the type of schedule for the current undercover agent in the Schedule Type field. 6. Beside the Event Marker area, accept the default event marker Message. If you want, you can later click Select and then select Content. (The Content selection is used to work with content events that originate from ECM servers. By comparison, the Message selection is used to work with message events that originate from business process definitions, JMS listeners, or web services that you have created.) 7. Under Details, click the drop-down list next to Queue Name to select the queue that you want from the following options: Table 1. Available queue options Option Async Queue SYNC_QUEUE_1 SYNC_QUEUE_2

Description Allows Event Manager jobs to run at the same time. Forces one job to finish before the next job can start. By default, three synchronous queues are available. Forces one job to finish before the next job can start. By default, three synchronous queues are available.

234

SYNC_QUEUE_3

Forces one job to finish before the next job can start. By default, three synchronous queues are available.

Note: For more information about Event Manager jobs, monitoring those jobs, and creating and maintaining Event Manager execution queues, see Maintaining and monitoring IBM Business Process Manager Event Manager. When you install and run the process on a Process Server in a test or production environment, the queue that you select must exist in that environment in order for the undercover agent to run. 8. Beside the Implementation area, accept the default selection Variable or select Service (if necessary). Use a variable implementation to pass events directly from the undercover agent to the business process definition (BPD). By comparison, use a service implementation to process information about events by adding business logic or decisions. 9. If you selected Variable, the default variable type NameValuePair is already selected. However, you can click Select to choose a different existing variable type or you can click New to create a new variable type. 10. If you selected Service, the default attached service Default BPD Event is already selected. However, you can click Select to choose a different existing service or you can click New to create a new general system service. 11. Ensure that the Enabled check box is selected.Note: If this check box is not selected, the Event Manager does not run the undercover agent when the message is received or sent. (The Event Manager monitor might show that the Event Manager has run the undercover agent, but if this check box is not selected, the execution does not occur.) 12. In the Parameter Mapping section, select the Use Default check box if you want to use the default value of the input variable in the attached service. If the input variable of the attached service does not have a default value, this check box is disabled.Type a value in the text box if you want to map a constant value to the input variable of the attached service. For example, you might use a constant for testing purposes. In most cases, the required values are included in the incoming message event and no action is required here. 13. In the Event section, IBM BPM provides a default ID that is unique in the Event Message field. This ID represents the event message for IBM BPM processing. If you are posting a message to IBM BPM Event Manager from an external system, the ID in this field is the event name that you need to include in the XML message. See Posting a message to IBM Business Process Manager Event Manager for more information about the message structure. If you are using a web service to enable an external application to call into IBM BPM, you should not alter this ID. IBM BPM seamlessly uses this ID if you create an inbound integration as described in Building a sample inbound integration. 14. Open the BPD that includes the message event to which you want to attach the undercover agent. For example, if you want a particular process to start when a new customer record is created in an external system, you can associate the start event in the BPD with an undercover agent that handles that incoming 235

event.Note: Ensure that the sender and receiver of a message both use the same undercover agent. For example, if the sender of a message is a message end event in another BPD, then select the same undercover agent for both the receiving start event and the sending message end event in the other BPD. Tip: If you occasionally use inbound messages, consider using durable subscription events. Durable subscriptions are Java Message Service (JMS) subscriptions that persist and store subscribed messages even when the client is not connected. The durable messages accumulate, even if you select the check box to make them consumable. Periodically use the BPMDeleteDurableMessages command for deleting durable subscription events. 15. Click the message event in the BPD to select it. 16. Click the Implementation option in the properties. 17. In the Message Trigger section, click Select next to Attached UCA and pick the undercover agent created in the previous steps. 18. Click Save and switch back to the undercover agent editor. 19. In the undercover agent editor, you can click Run Now if you want to test the undercover agent and monitor it as described in Maintaining and monitoring IBM Business Process Manager Event Manager. Parent topic:Undercover agents Related information: Attaching the undercover agent to the message event BPMDeleteDurableMessages command

236

Creating and configuring an undercover agent for a scheduled message event You can create an undercover agent (UCA) that invokes a service as the result of a message event that occurs on a regular schedule.

Before you begin To perform this task, you must be in the IBM® Process Designer desktop editor.

About this task Scheduled undercover agents do not run on the Process Center server unless you click Run Now. If you are testing a business process definition (BPD) that includes scheduled undercover agents, and you want to ensure that the undercover agents run on time, run the BPD on a Process Server in one of your runtime environments, such as your development, test or staging environment.

Procedure 1. Open the Process Designer desktop editor. 2. Open a process application in the Designer view. 3. Select the plus (+) sign next to Implementation and then select Undercover Agent from the list. 4. In the New Undercover Agent window, enter the following information: - Name: Type a name for the new undercover agent. - Schedule Type: Select Time Elapsed from the drop-down list. - Click Finish. 5. In the Common section, you can type a description of the undercover agent in the Documentation text box. 6. In the Scheduler section, you can see the type of schedule for the current undercover agent. After you have configured and saved the undercover agent, you can click Run Now if you want to test the undercover agent and monitor it as described in Maintaining and monitoring IBM Business Process Manager Event Manager. 7. Under Details, click the drop-down list next to Queue Name to select the queue that you want from the following options: Table 1. Available queue options Option Async Queue SYNC_QUEUE_1 SYNC_QUEUE_2

Description Allows Event Manager jobs to run at the same time. Forces one job to finish before the next job can start. By default, three synchronous queues are available. Forces one job to finish before the next job can start. By default, three synchronous queues are available.

237

SYNC_QUEUE_3

Forces one job to finish before the next job can start. By default, three synchronous queues are available.

Note: For more information about Event Manager jobs, monitoring those jobs, and creating and maintaining Event Manager execution queues, see Maintaining and monitoring IBM Business Process Manager Event Manager. When you install and run the process on a Process Server in a test or production environment, the queue that you select must exist in that environment in order for the undercover agent to run. 8. Ensure the service shown as the Attached Service is the one that you want to invoke according to the specified schedule. If not, click Select to choose a different service. 9. Ensure that the Enabled check box is selected.Note: If this check box is not selected, the undercover agent will not run. 10. In the Parameter Mapping section, select the Use Default check box if you want to use the default value of the input variable in the attached service. If the input variable of the attached service does not have a default value, this check box is disabled.Type a value in the text box if you want to manually map a constant value to the input variable of the attached service. For example, you might use a constant for testing purposes. 11. Scroll down to the Time Schedule section and use the available options to establish a schedule.For example, if you want to start the attached service every weekday at midnight, use the Ctrl key to select the options that are selected in the following image:

You can select multiple contiguous items by pressing the Shift key, clicking the first in the series, and then clicking the last in the series. To select multiple noncontiguous items, press the Ctrl key each time you click an item. Note: The On the hour value is selected by default in the last column of the Time Schedule section. If you clear this selection and you do not make any other selection in the column, the On the hour value will be used even though it is not selected. Note: If you select the First value and also select multiple weekdays, the undercover agent will run on the first occurrence of each selected day for the selected months. For example, if you select First and also select Monday, Tuesday, and Thursday, the undercover agent will run on the first Monday, Tuesday, and Thursday that occur in the selected months. Similarly, if you select the Last value and also select multiple weekdays, the undercover agent will run on the last occurrence of each selected day for the selected months. For example, if you select Last and also select Monday, Tuesday, and Thursday, the undercover agent will run on the last Monday, Tuesday, and Thursday that occur in the selected months. 238

12. Open the BPD that includes the message event to which you want to attach the undercover agent. For example, if you want a particular process to start at the same time each day, you can associate the start message event in the BPD with an undercover agent that establishes the required schedule. 13. Click the message event in the BPD to select it. 14. Click the Implementation option in the properties. 15. In the Message Trigger section, click Select next to Attached UCA and select the undercover agent created in the previous steps. Parent topic:Undercover agents

239

Creating and configuring an undercover agent for a content event To obtain information about document or folder events on an Enterprise Content Management (ECM) server, you must create and configure a content undercover agent that works with your event subscription. A content undercover agent (UCA) is used to initiate a BPM Start or Intermediate event when specific content changes occur on an ECM server. It is conceptually similar to a message undercover agent, but it has a specialized Content marker to differentiate it from a Message marker.

Before you begin To perform this task, you must be in the IBM® Process Designer desktop editor. The following procedure describes how to create a content undercover agent without consideration for some of the other components that are required to detect and respond to ECM events, such as an event subscription. If you need to create a content undercover agent and all of the other required components as well, you should follow the instructions in the topic Subscribing to document and folder events: the end-to-end approach. This end-to-end approach is a simpler approach than creating each component on a stand-alone basis. It automatically creates some resources that you would otherwise need to create manually.

Procedure 1. Open the Process Designer desktop editor. 2. Open a process application in the Designer view. 3. Create a content undercover agent by completing the following steps: A. Click the plus (+) icon beside Implementation and then select Undercover Agent. The New Undercover Agent wizard opens. B. In the Name field, specify a name for the new undercover agent. C. In the Schedule Type drop-down list, select On Event. D. Click Finish. The undercover agent opens in the undercover agent editor. 4. Configure the content undercover agent by completing the following steps in the undercover agent editor: A. Beside the Event Marker area, click Select and then select Content. (Use the Content selection to work with content events that originate from ECM servers. By comparison, the Message selection is used to work with message events that originate from BPDs, JMS listeners, or web services that you have created.) B. Beside the Implementation area, accept the default selection Variable or select Service (if necessary). Use a variable implementation to pass events directly from the undercover agent to the business process definition (BPD). By comparison, use a service implementation to process information about events by adding business logic or decisions. C. If you accepted Variable as your implementation, the default variable type ECMContentEvent is used and it cannot be changed. D. If you selected Service as your implementation, the default attached service Default ECM Event is already selected. However, you can click Select beside

240

the Attached Service area and choose a different attached service for the undercover agent. E. Ensure that the Enabled check box is selected, which enables the content undercover agent to run. F. In the Parameter Mapping section, select the Use Default check box if you want to use the default value of the input variable in the attached service. If the input variable of the attached service does not have a default value, this check box is disabled. You can type a value in the field to manually map a constant value to the input variable of the attached service. For example, you might use a constant for testing purposes. G. Click Save. H. If you accepted the Content event marker and you need to create an event subscription for the undercover agent, click Add Event Subscription and follow the instructions in the topic Creating and configuring event subscriptions . I. After you have configured and saved the content undercover agent, you can click Run Now to test the content undercover agent and monitor it as described in Maintaining and monitoring IBM Business Process Manager Event Manager.

Results The new configured content undercover agent is displayed in the Undercover Agents section of the Implementation library list.

Parent topic:Undercover agents Parent topic:Performing modeling tasks for inbound events

241

Documenting development artifacts As you develop your process application, you might want to capture information about the artifacts that you are creating. Each artifact in IBM® Process Designer has a documentation field for this purpose. You can enter text or links to external resources such as web sites or attachments.

Procedure To enter documentation for an artifact: 1. Open the artifact in Process Designer. 2. Switch to the Overview tab. 3. Enter your text in the Documentation field.

What to do next Restriction: The documentation field allows a maximum of 200,000 characters, including hidden formatting characters. Long documentation that approaches this limit can impact performance. Consider the following options: - Reduce the size of the documentation. - Simplify the formatting, such as removing tables and text formatting. - Move the documentation content to a separate file and link to or attach the file. See Linking to external information.

- Linking to external information To include a link to an external source, paste a link into the Description field of the process application or toolkit, or the Documentation field of an artifact in IBM Process Designer. - Process documentation location links When you work with process applications and toolkits in IBM Process Center or IBM Process Designer, you can share the location of an artifact in your development flow by copying a link to that artifact. Parent topic:Modeling processes

242

Linking to external information To include a link to an external source, paste a link into the Description field of the process application or toolkit, or the Documentation field of an artifact in IBM® Process Designer. When you work with process applications or toolkits, you might need to link to related information that is outside of the IBM Business Process Manager environment. For example, you might want to link to a website or a wiki page. You can also reference a change request stored in a change management system or a test case in a quality management system. These kinds of links can be used to achieve traceability or provide details about the fixes and features that went into a new process application snapshot. Parent topic:Documenting development artifacts

Adding a link You can add a link to an external resource in a process application or toolkit description.

Before you begin To add a link in the documentation field in IBM Process Designer, you must use the Process Designer desktop editor.

Procedure To add a link to an external source, complete the following steps: 1. Log in to IBM Process Center or IBM Process Designer and select a process application or toolkit. 2. Do either of the following steps: A. In Process Center, click the Manage tab. The B. In Process Designer, select the artifact in the process application or toolkit for which you want to add a link to an external resource and click the Overview tab, or open the Properties editor. 3. Do either of the following steps: - In Process Center, click inside the Description field. - In Process Designer, click the Documentation Edit link in the Common Section of the Overview, or in the Properties editor. In Process Center, the inline editor displays showing you a standard formatting toolbar. In Process Designer, a rich text editor window opens that shows a standard formatting toolbar. 4. To add a link, click the Insert Link icon on the toolbar and complete the fields in the Add Link window. When you access a specific content source, you might be prompted to log in to the source. You must log in with a user ID and password that provides access to that content source. The link source must be registered as a remote content source with Process Center using the Create Registration option. For more information about registering a remote content source, see Using remote assets.Note: In Process Center, the attachment link type is

243

available only when you create a new snapshot, or edit an existing snapshot. When you create a new snapshot, you can create the attachment link either to an existing design file, or to a new file. When you edit an existing snapshot, you can create the attachment link only to an existing design file. Also, when you create an attachment link to a new file: - The files that you add must be 100 MB or less. - The name of the file that you add must be less than 64 alphanumeric characters. - The accumulated total file size for a process application must be less than 600 megabytes. 5. Optional: You can specify the relationship type of the link and the asset type that the link is associated to. The asset types are determined by the type of content source that you are using in your project. When you select a link type, it can be modified by any asset type that you select. For example, if you select Implements as the relationship type and Defect as the asset type, the description of the artifact is modified with an option that defines the link as implementing a defect. The link displays as a defect. The following table identifies the default link and asset types.Table 1. Link options Type Relationship Type Unspecified Affected by Implements Related to Resolves Tested by Uses Asset Type Unspecified Change Request Defect Requirement Service Test

Description No specific link type is specified Defines the link target as affected what is defined by the selected asset type Defines the link target as implementing what is defined by the selected asset type Defines the link target as associated to what is defined by the selected asset type Defines the link target as resolving what is defined by the selected asset type Defines the link target as tested by what is defined by the selected asset type Defines the link target as using what is defined by the selected asset type No specific asset type is specified Defines the asset type as a change request Defines the asset type as a defect Defines the asset types a project requirement Defines the asset type as a service that can be implemented Defines the asset type as a test

244

Editing an existing link When you have your link setup, you might need to update the link or change it to a new link.

Before you begin To edit a link in IBM Process Designer, you must use the Process Designer desktop editor.

Procedure To edit an existing link, complete the following steps: 1. Log in to Process Center or Process Designer and select a process application or toolkit. 2. Do either of the following steps: - In Process Center, click the Manage tab. - In Process Designer, select the artifact in the process application or toolkit for which you want to add a link to an external resource and click the Overview tab, or open the Properties editor. 3. Do either of the following steps: - In Process Center, click inside the Description field. - In Process Designer, click Edit in the Overview tab or the Properties editor. In Process Center, the inline editor displays showing you a standard formatting toolbar. In Process Designer, a rich text editor window opens that shows a standard formatting toolbar. 4. Place the cursor on the link and click the link text. The Edit Link window opens. You can now edit the link or the link name.

245

Process documentation location links When you work with process applications and toolkits in IBM® Process Center or IBM Process Designer, you can share the location of an artifact in your development flow by copying a link to that artifact. You might need to provide a link to an artifact, such as a business process definition (BPD), outside of IBM Business Process Manager. For example, you might want to email the Process Center location of a BPD or a process application. Perhaps you might need to share a link to an artifact within another artifact, such as by sharing a link to a process application in the documentation of another process application. Parent topic:Documenting development artifacts

246

Using external implementations You can create external implementations for activities that are handled by applications outside of IBM® Business Process Manager. For example, you can model an activity that is run by a custom Eclipse RCP or Microsoft .NET application. To use an external implementation to implement an activity in a business process definition (BPD), complete the tasks listed in this section. Tip: In product releases older than V7.5.1, external implementations were referred to as external activities.

1. Building a custom application to implement an activity Build a custom application using the IBM Business Process Manager Web API to implement an activity in a BPD. 2. Creating an external implementation Create an external implementation when you want to reuse an existing external application or create an external application to handle one or more steps in your process. 3. Using an external implementation to implement an activity Select a custom application to implement a particular activity (step) in a BPD. Parent topic:Modeling processes

247

Building a custom application to implement an activity Build a custom application using the IBM® Business Process Manager Web API to implement an activity in a BPD. If you want to build a custom application to implement an activity within a process, you must use the IBM Business Process Manager Web API to enable your custom application to interact with IBM BPM. For example, the IBM BPM Web API provides operations that enable you to pass variables from an IBM BPM BPD to a custom application and then back to the BPD for continued processing. Using the IBM BPM Web API sample external implementation IBM Business Process Manager includes a sample external implementation that illustrates how to use IBM BPM Web API operations when developing a custom application to enable process participants to complete a particular step within a process. The IBM Process Designer enables you to include these custom applications in your Business Process Definitions (BPDs) and model them as external implementations. The Samples Exchange on Blueworks Live includes a sample external implementation. The sample external implementation is a custom Eclipse application that enables managers to either approve or reject expense reports from their employees. It represents one step in a process and can be modeled as an external implementation in IBM Process Designer. Download the samples archive file from Sample Exchange Home. Search using keywords web-api. If you import the BPD External Implementation Library and other associated components in the ExpenseApproval.twx file from the sample, the Eclipse application, combined with the corresponding library items, is a complete working example of external implementations.

Parent topic:Using external implementations Next topic:Creating an external implementation Related concepts: Web API and external implementations

248

Creating an external implementation Create an external implementation when you want to reuse an existing external application or create an external application to handle one or more steps in your process.

Before you begin To perform this task, you must be in the IBM® Process Designer desktop editor.

About this task Using the external implementation function is similar to using the service functions like an integration service or web service. However, unlike those service functions that are designed for a specific area like web services or integration, the external implementation is more generic in nature. When a step in a business process is implemented with an external implementation, the business process halts and waits for input from the external application. To create an external implementation, use the Web APIs or REST APIs. The previous topic discusses a sample that creates an external implementation with the Web APIs. To create an external implementation with the REST APIs, these articles are helpful. Using the REST APIs in IBM Business Process Manager and Integrating a business process application with an external system using the REST API. The related links at the bottom of this topic link to more information on the Web APIs and REST APIs. When you create an external implementation in IBM Process Designer, you need to know the properties to use to identify and run the custom application. If you did not build the custom application, you need to coordinate with the developers to ensure that you provide the appropriate properties in IBM Process Designer.

Procedure 1. Open the Process Designer desktop editor. 2. Open a process application in the Designer view. 3. Click the plus sign next to Implementation and select External Implementation from the list of components. 4. Supply a descriptive name for the new external implementation. 5. Click Finish. 6. In the Common section of External Implementation, optionally provide a description in the Documentation text box. 7. In the Custom Properties section, specify the properties to identify and run the external application.For example, for an external Eclipse RCP application, you might add custom properties to pass the Java Class name of the form to use for an activity or an application-specific identifier to look up the implementation by another means. Alternatively, you might use the external application name or system ID to find the implementation. You can create parameters with a special meaning. For example, suppose you need to pass a URL address as a custom property? In the Custom Properties

249

section you could use url as the name and then add a value that is the URL itself (http://mysite.com...). You can also use this section to pass data to variables in a client that were instantiated with a constructor. Note: You can add custom properties to pass static metadata about the implementation to the external application. For dynamic data, which would be different for each process instance or environment, use the Parameter Details section as outlined in the following step. 8. In the Parameters section, add the parameters for the external implementation by clicking Add Input or Add Output.For example, if the external implementation provides an interface in which a manager can either approve or reject an expense report, it might include input parameters for the expense report data and output parameters for the decision that the manager makes and the justification for his decision. Be sure to account for all process data that the external implementation requires to complete successfully and also for any data required from the external activity by subsequent activities. 9. Click Save in the main toolbar.

What to do next You can use an external implementation with Process Portal. In the Custom Properties section add the URL for Process Portal as shown earlier. In the article, Load External Activity URLs from Teamworks Portal, you will see how to retrieve a task ID from the business process to work with a specific task.

Parent topic:Using external implementations Previous topic:Building a custom application to implement an activity Next topic:Using an external implementation to implement an activity Related concepts: Using the web service API in IBM BPM Related information: Developing client applications that use IBM BPM REST APIs

250

Using an external implementation to implement an activity Select a custom application to implement a particular activity (step) in a BPD.

Before you begin To perform this task, you must be in the IBM® Process Designer desktop editor.

About this task The following steps describe how to select a custom application as the implementation for an activity in a BPD:

Procedure 1. Open the Process Designer desktop editor. 2. Open a BPD and click the activity that you want to implement using a custom application. 3. Click the Implementation tab in the properties. 4. Under Implementation, select the User Task or System Task option from the displayed list. 5. Click the Select button to choose an external implementation from the library.If the external implementation has not been created, click the New button and follow the steps in Creating an external implementation to create a new external implementation. 6. In the Task Header section, specify the following properties: Table 1. Properties in the Task Header section Property Subject

Narrative

Action Type a descriptive subject for the task that is generated in IBM Process Portal when you run the BPD. You can also use the IBM Business Process Manager embedded JavaScript syntax (for example, ) to express the subject. Type an optional description. You can also use the IBM BPM embedded JavaScript syntax to express the narrative. Restriction: Do not use JavaScript variable references in task narratives if you need the data to be available after the task completes. Once a task is complete, IBM BPM removes the data for completed tasks to conserve space. Instead, store the data items in another location, such as a database.

251

Note: For the following properties (in the Priority Settings section) you can click the JS button for an option if you prefer to use a JavaScript expression with predefined variables to establish the priority settings. 7. For the Priority field, click the drop-down list to select one of the default priority codes: Very Urgent, Urgent, Normal, Low, or Very Low. 8. For the Due In field, you can enter a value in the text box and then choose Minutes, Hours, or Days from the drop-down list. (When you choose Days, you can use the text box after the drop-down list to include hours and minutes in your specification.) You also have the option of using the variable selector next to the text box to choose an existing variable from the library. at run time, the variable should reflect the value that you want for the time period. Be sure to select the option that you want from the drop-down list: Minutes, Hours, or Days. 9. For the Time Period field, click the drop-down list to select one of the options. For example, select 24x7 if you want 24 hours a day, seven days a week to be the time period in which the resulting tasks from the current activity can be due. Note: You can leave the Schedule, Timezone, and Holiday Schedule fields set to (use default). If you do, the work schedule specified for the BPD is used. See Setting the work schedule for a BPD for more information. 10. For the Time Zone field, click the drop-down list to select the time zone that you want to apply to the tasks that result from the current activity. For example, you can select US/Pacific for users who work in California. 11. For the Holiday Schedule field, you can leave the setting at (use default) as described in the preceding note or you can click the JS button if you prefer to use a JavaScript expression. Each Holiday Schedule is made up of a list of Dates. If you choose JavaScript, you can enter either a String (or Stringgenerated JavaScript) or JavaScript that returns a TWHolidaySchedule variable. If you use a String, then IBM BPM looks up the holiday schedule by name according to those rules. If you use a TWHolidaySchedule variable, then IBM BPM assumes that the holiday schedule is filled in appropriately. (Go to the System Data toolkit and open the TWHolidaySchedule variable to view its parameters.) 12. Click the Data Mapping tab in the properties.Because you added the input and output parameters for the external implementation when you created it, the Data Mapping tab for the activity in the BPD should include those parameters. Under Input Mapping, click the auto-map icon in the upper-right corner, and then click the auto-map icon in the upper-right corner of the Output Mapping section. For more information about mapping variables, see Business objects and variables in Process Designer. 13. Save the implementation. Parent topic:Using external implementations Previous topic:Creating an external implementation

252

Integrating with web services, Java and databases You can configure IBM BPM processes to communicate with an external system to retrieve, update, or insert data. And, external applications can call into IBM BPM to initiate services. You can manage inbound and outbound communication with external systems using undercover agents, web services, and integration services. IBM® Business Process Manager supports both outbound and inbound integration as described in the following table: Table 1. Supported integration types Integration type Outbound

Inbound

Description

Required IBM BPM components IBM BPM communicates Integration service, IBM with an external system to Case Manager Integration retrieve, update, or insert Service, or Undercover data. Agent An external system calls Undercover Agent and into IBM BPM to initiate a Web Service service.

- Creating outbound integrations Outbound integrations enable business process authored in Process Designer to interact with other systems, such as a web service, a content management system, or an external database. Depending on the system that you are integrating with, you can implement the integration service using an Integration Service implementation or an IBM Case Manager Integration Service implementation. - Creating inbound integrations For inbound integrations that involve an external system or application calling into IBM Business Process Manager to kick off a service, you need to build several IBM BPM components and corresponding services. - Web services compatibility Web services conform to a flexible architecture that allows variation in web services implementations. This variation unfortunately can lead to compatibility problems. Parent topic:Modeling processes

253

Creating outbound integrations Outbound integrations enable business process authored in Process Designer to interact with other systems, such as a web service, a content management system, or an external database. Depending on the system that you are integrating with, you can implement the integration service using an Integration Service implementation or an IBM® Case Manager Integration Service implementation. To create an outbound integration with an external database, use the predefined SQL Integration services that are available in the IBM BPM System Data Toolkit.

Integration Service implementations Integration Service implementations can contain integration step types that you can configure for the system that you are interacting with. For example, a Web Service Integration step is useful if you are not passing volumes of information. A Java Integration step gives you access to the features of the Java language, including published Java libraries and APIs. The following table describes the integration step types that are available for Integration Service implementations. Table 1. Step types that can be used in an Integration Service implementation Integration step type Web Service Integration

Java Integration

Content Integration

Invoke UCA

Description Uses a SOAP connection to access objects from a web service. A Web Service Integration step hides the complexity of the underlying WSDL, SOAP request, and SOAP response. It also converts inputs into the appropriate XML and outputs into the appropriate IBM BPM variables.Attention: The RPC/encoded WSDL support is deprecated in IBM BPM V8. Consider replacing RPC/encoded web services with documentation/literal wrapped web services. For more information, see Deprecated and removed features of IBM Business Process Manager V8.5.5 Calls methods from a Java class and interfaces with most third-party Java APIs, and thus supports various integration scenarios. Enables business processes that are developed in Process Designer to work with an Enterprise Content Management system. Uses an undercover agent (UCA) to invoke an IBM BPM service or a business process definition (BPD).

IBM Case Manager Integration Service implementations An IBM Case Manager integration service is the means of accessing case management cases from a business process both for searching and updating case 254

management data.Table 2. Step types that can be used in an IBM Case Manager Integration Service implementation Integration step type IBM Case Manager Integration

Invoke UCA

Description Enables business processes that are developed in Process Designer to work with an IBM Case Manager case management solution. Invokes an IBM BPM service or a BPD..

- Creating outbound integrations to web services Integration services enable outbound integration with web services so that processes can retrieve and update data that is stored on an external system. You can use a generic web service connector or a Web Service Integration step to enable the access to the web service. - Calling a Java method in an integration service If the implementation for an activity requires calling methods from a Java class, you can use the Java Integration step in an integration service. - Sending attachments using an SMTP server With a Java Integration component, you can send attachments by using a Simple Mail Transfer Protocol (SMTP) server. - Using IBM Business Process Manager SQL Integration services To integrate with an external database, you can use the SQL Integration services available in the IBM BPM System Data Toolkit. Parent topic:Integrating with web services, Java and databases Related information: Building an Integration service Integrating with Enterprise Content Management (ECM) systems Integrating BPDs with IBM Case Manager cases Undercover agents Using IBM Business Process Manager SQL Integration services

255

Creating outbound integrations to web services Integration services enable outbound integration with web services so that processes can retrieve and update data that is stored on an external system. You can use a generic web service connector or a Web Service Integration step to enable the access to the web service. A generic web service connector, Call WebService via SOAP, is provided in the System Data Toolkit. This connector abstracts the complexity of the web service implementation and requires only minimal configuration. For more information on using the connector, see Calling a web service using a SOAP connector. However, if you have specific requirements on the web service, such as the type of security or message encryption, use a Web Service Integration step to integrate with the service. - SOAP headers Use a SOAP header to include application-specific context information in the web service SOAP request and response messages. - Creating implicit SOAP headers for outbound web service integrations SOAP headers are used to communicate application-specific context information within SOAP request and response messages. This context information can be anything that you need to send along with the web service operation parameters. An implicit SOAP header is one that is not defined in the web service WSDL document. As part of your outbound web service integrations, you can add implicit SOAP headers to your web service request messages and retrieve SOAP headers from response messages. - Adding a web services server You can add one or more web services servers to your process application. Each web services server describes the location of a web service endpoint and can be referenced when you define an outbound web service integration. This reference enables the sharing of configuration information between web service integrations that starts the same endpoint, eliminating the need to configure similar information multiple times. In addition, if you need to change the information that is associated with a particular endpoint, you can change the web services server information and the updated information can be used by any web service integration that references the web services server. - Configuring a Web Service Integration component Use a Web Service Integration component to invoke a web service that is hosted externally. You can configure the WSDL properties, SOAP header information, authentication, signature and encryption properties for the web service integration. - Security for Web Service Integration steps You can secure a web service using policy sets and bindings or by manually creating an authentication method that requires a user name and password. - Web service faults Faults are a way of handling exceptions in web services at run time. A fault that helps a user understand a problem and what he can do about it leads to a quick resolution of the problem. If you use a Web Service Integration step from the integration service palette to call an outbound web service, your step can catch

256

and handle faults. - Serialization of IBM Business Process Manager objects for use in web services You can add metadata to IBM BPM objects to control how those objects are serialized into XML elements in a SOAP request for web services. - Setting up message-level encryption Message-level encryption provides confidentiality by applying encryption to all or parts of a SOAP message. The encryption spans the entire communication chain between the consumer and the provider. To take advantage of this type of encryption in integration services for BPDs, you must enable the corresponding configuration settings. - Troubleshooting web services outbound web service integrations Learn how to solve problems that you may have when using web service integration steps in your services. - Considerations when using WSDL with multiple XSD or WSDL imports When you are using Web Services Description Language (WSDL) with multiple XSD or WSDL imports for an outbound web service component, you can merge all of your XSDs into one WSDL file to avoid multiple connections to your endpoint. - Troubleshooting XML schema messages for web service integrations When you are using a Web Service Integration component, you might encounter error and warning messages if you use XML constructs that are not supported or have problems in Process Designer. Parent topic:Creating outbound integrations Related information: Building an Integration service Supported web service standards

257

SOAP headers Use a SOAP header to include application-specific context information in the web service SOAP request and response messages. SOAP is a lightweight, XML-based protocol that you can use to exchange information in a decentralized, distributed environment. You can use SOAP to query and return information and to invoke services across the Internet with SOAP messages. SOAP messages are exchanged in a request-and-response format. When IBM® Business Process Manager sends a request to a web service, the web service returns the requested values. These values are specified in a SOAP message. This XML-based protocol consists of three parts: - An envelope, which defines what is in the message and how to process it - A set of encoding rules for expressing instances of application-defined data types - A convention for representing procedure calls and responses Each SOAP message must contain a SOAP envelope element. The SOAP envelope describes what is in the message and provides instructions about how to process it. The SOAP envelope has two child elements: a body (required) and a header (optional). All the elements must be declared in the namespace for the SOAP envelope. The SOAP body element contains the SOAP message that is associated with a web services request or response. The body typically contains the value of input parameters for a request message and the value of output parameters for a response message. The SOAP header is an optional section in the SOAP envelope, although some WSDL files require that a SOAP header is passed with each request. A SOAP header contains application-specific context information (for example, security or encryption information) that is associated with the SOAP request or response message. There is only one SOAP header section in a SOAP request. If the SOAP header element is present, it must be the first child element of the envelope element. SOAP headers can be input, output, or input and output, and you do not need to specify them in the WSDL file. Important: For outbound web services, if you have defined the SOAP header in the header section of a web service integration component, use the same type that is defined in the WSDL file, or use the basic XML schema definition (XSD) type. Otherwise, you cannot automatically map the SOAP header variable or change its values from the data mappings section. In IBM BPM Standard, you can populate a SOAP header in the following ways: - Define the SOAP header in the WSDL definition as part of the SOAP binding. You indicate these headers by by using a tag in the and elements in the WSDL file. When IBM BPM sends a request to the server that hosts the web service, the SOAP message includes the SOAP header. - Copy headers directly from system variables, or from user-defined variables of the correct type, into the predefined request and response SOAP header data types. This SOAP header is considered implicit because it is not part of the SOAP

258

binding. For more information, see Creating implicit SOAP headers for outbound web service integrations. - Capture an incoming SOAP header in the response. In the Properties view, select the Data Mapping tab and map the incoming SOAP header to an existing SOAPHeaders variable. System variables are supplied or you can create your own variables of the SOAPHeaders type. This SOAP header is also considered implicit because it is not defined in the WSDL file.

Parent topic:Creating outbound integrations to web services Related information: Creating implicit SOAP headers for outbound web service integrations Retrieving SOAP headers from the SOAP response message

259

Creating implicit SOAP headers for outbound web service integrations SOAP headers are used to communicate application-specific context information within SOAP request and response messages. This context information can be anything that you need to send along with the web service operation parameters. An implicit SOAP header is one that is not defined in the web service WSDL document. As part of your outbound web service integrations, you can add implicit SOAP headers to your web service request messages and retrieve SOAP headers from response messages.

About this task Note: The Headers tab in the Properties view for web services is deprecated. The method for adding implicit SOAP headers described here is now the preferred method. All the variables that you declare in IBM® Process Designer are JavaScript variables. You can use them inside service definitions and also in expression evaluations inside JavaScript code snippets. - Adding SOAP headers to a SOAP request message You can add a SOAP header to a request message by creating a variable of type SOAPHeader or SOAPHeaders. You can then map that variable to the SOAP header request. - Retrieving SOAP headers from the SOAP response message You can retrieve SOAP headers from a response message by creating a variable of type SOAPHeaders and then mapping that variable to the SOAP header response.

Parent topic:Creating outbound integrations to web services Related information: Using JavaScript variables and objects inside Process Designer SOAP headers

260

Adding SOAP headers to a SOAP request message You can add a SOAP header to a request message by creating a variable of type SOAPHeader or SOAPHeaders. You can then map that variable to the SOAP header request.

Procedure 1. Create an integration service that includes a web service integration component. 2. Select the web service integration component and click the Variables tab above the diagram area. 3. Create the private variable that you will later map to the SOAP header of the request message. To add a single header entry to the request message, use the variable type SOAPHeader. To add multiple headers to the request message, use the variable type SOAPHeaders. 4. Initialize the variable that you created in step 3. You can initialize the variable in three ways: - Define a default value on the page where you created the variable. - Add JavaScript code to a server script component. - Click Pre & Post and add JavaScript code to the Pre-execution Assignments section The following example of JavaScript code initializes a private variable, requestHeader, which is of the type SOAPHeader and contains a single header entry: tw.local.requestHeader.name = "sessionId"; tw.local.requestHeader.nameSpace = "http://acme.com"; tw.local.requestHeader.value = "1237314";

Note: Make sure namespaces are fully qualified, as they are in the examples. Note: Try to avoid white spaces in a SOAP header value. Best practice is to add the XML snippet without any extra white space. You can include more than one header. The following example of JavaScript code initializes two SOAP headers and adds them to the requestHeaders private variable, which is of the type SOAPHeaders and contains multiple headers: // Initialize the "subscriptionId" header var header1 = new tw.object.SOAPHeader(); header1.name = "subscriptionId"; header1.nameSpace = "http://acme.com"; header1.value = "123-4567-9012";

// Initialize the "auditLogUUID" header var header2 = new tw.object.SOAPHeader(); header2.name = "auditLogUUID"; header2.nameSpace = "http://acme.com"; header2.value = " Save All.

266

Parent topic:Creating outbound integrations to web services Related information: Configuring a web service server at run time Supported web service standards WS-Security specification

267

Configuring a Web Service Integration component Use a Web Service Integration component to invoke a web service that is hosted externally. You can configure the WSDL properties, SOAP header information, authentication, signature and encryption properties for the web service integration.

Before you begin If the web service uses the SSL protocol, the certificate that is used by the target host must be installed in the IBM® BPM environment as described in Secure communications using SSL. If the certificate is not installed, you get a No trusted certificate is found error when you try to discover the WSDL implementation properties. Ensure that you know whether the service that you are invoking requires any additional SOAP headers in web service messages. Conversely, if the web service has to process the request message, for example, for the security information, contact the web service provider to ensure that they can support your header. If the web service uses X509 client and server certificates for both encrypting and signing the request, the certificates must be added to the IBM Business Process Manager keystore. In addition, configuration changes must be made to the 100Custom.xml file as described in Setting up message-level encryption. The 99Local.xml file sets the use-jaxws property to true. In most cases this setting is appropriate for an integration with a web service as many web services use the Java API for XML Web Services (JAX-WS). If the web service you are integrating with, however, uses a Remote Procedure Call (RPC) encoding style then you should set the use-jaxws property to false.

Procedure 1. In the Process Designer Designer view, create an integration service for the process application. 2. Drag a Web Service Integration component from the palette to the diagram, and click the component to open the properties. 3. Specify the location and properties of the web service WSDL file by clicking the Implementation properties tab. Select the Discovery Scheme you want from the drop-down list.From process application settings lets you select a configuration from the web service server configurations. Provide inline configuration lets you specify your own web service configuration as shown in the following sub steps. A. Enter a value in the WSDL URI field. You can enter a URL, or use the Registry Explorer to discover it. 1. Click Browse to start the Registry Explorer, and then select the registry type from the list. 2. Select a registry URL or enter a new one. 3. For protected web services, enable the Is Protected check box, and provide the user name and password, and click Next. 4. Enter the name of the web service and click Search services. You can include wildcard characters in the name; for a UDDI registry use a percent

268

sign (%), for a WebSphere Service Registry and Repository registry use an asterisk (*). 5. Select a web service, click Next to see detailed information, and then Finish . If you use the Registry Explorer, the WSDL URL, Protected WSDL, Username, and Password fields are populated automatically. If you enter the URL manually, you must also provide the other information about the WSDL file if needed. B. Click Discover to find the WSDL file and obtain the list of operations. Then select an operation from the list. C. Optional: Specify that the endpoint address URL can be overridden and provide an alternative endpoint address. You might want to specify an alternative endpoint address, for example, if you have different endpoints for development, test, staging, and production environments; or if your production environment does not have direct internet access and requests are routed through a proxy server or gateway. You can enter the new address as a String value, for example, https://provider.com/services/myService, or as a JavaScript expression that is wrapped by . D. Extract the input and output variables from the WSDL file that are needed by the web service by clicking Generate Types. You can map the input and output variables in two ways. In the Properties view, select the Data Mapping tab and click the "Auto-map web service connector input (or output) parameters" icon. You can also manually create the variables using the functions in the Variables tab. Then you can map these variables to the web service input and output parameters in the Data Mapping section.If your web service integration component calls an inbound web service created in IBM BPM, you must generate the types again in the following cases. - The inbound web service uses a business object defined in the System Data Toolkit. The namespace of that business object uses a host name and a port specification. The types must be generated again for business objects (complex types) if the inbound web service's host name or port is changed in this situation. - The Target namespace scheme field is changed to the Per snapshot name value. The namespace of the WSDL file will use the snapshot name once you select this option. You must generate the types again for business objects (complex types) each time you create a snapshot for the inbound web service. 4. Optional: Add a SOAP header by creating a new variable in the Variables tab of type SOAPHeader or SOAPHeaders, then map that variable in the Data Mapping tab under Properties. For detailed instructions, see Creating implicit SOAP headers for outbound web service integrations. You can add a SOAP header to a SOAP request, for example, to pass additional context information to the web service. 5. Click the Security properties tab. Specify the type of security by selecting Use Basic Security or Use Policy Set. A. If you select Use Basic Security, specify the policy sets that are used by the 269

web service, and provide the user name and password. Specify the certificate, encryption, and signature settings for both the client application and the web service server. These settings ensure the integrity and confidentiality of the messages that are exchanged with the web service. B. If you select Use Policy Set, select the policy set and the policy binding from the drop-down lists.Policy Set: Specifies the name of the application policy set. Click Select to choose the policy set. The list you will see depends on the policies available on the server. Some default application policy sets include: WSHTTPS default, WSAddressing default, and Username WSSecurity default. You can also create additional application policy sets in the WebSphere Application Server Administrative Console. Deselecting a policy set also removes the policy binding. More information on policy sets can be found in the WebSphere Application Server Web Services Guide IBM Redbook. Policy Binding: Specifies the name of the general client policy set binding, which contains system-specific configuration parameters like username and password information. Click Select to choose the policy binding. The list you will see depends on the policy set bindings available on the server. Default policy set bindings include: Client sample and Client sample V2. You can also create additional policy set bindings in the WebSphere Application Server Administrative Console. Deselecting removes the policy binding. 6. Configure the input and output mappings for the parameters in the WSDL file by clicking the Data Mapping properties tab. Parent topic:Creating outbound integrations to web services Related information: Supported web service standards

270

Security for Web Service Integration steps You can secure a web service using policy sets and bindings or by manually creating an authentication method that requires a user name and password. To use policy sets and bindings, see the following topics: - Configuring a Web Service Integration component - Adding a web services server - Creating an inbound web service In the context of web service integration with BPDs, security can be required at design time and at run time.

Design time authentication If you are manually creating your own security, at design time you can enable protected WSDL in the implementation properties for the Web Service Integration step and provide the user name and password.Attention: The user name and password are sent as base64-encoded text strings in the HTTP basic authentication header. To prevent eavesdropping, use only SSL secured connections by ensuring that the URL starts with https://.

Run time authentication If you are manually creating your own security, authentication options for SOAP calls at run time are available in the security properties for the Web Service Integration step. The following table describes the information that you must provide for each supported option: Table 1. Input required for authentication options Option HTTP basic authentication

Description Requires a user name and password. IBM® BPM never stores the password in plain text in its database or export files, and no plain text passwords are required in IBM BPM configuration files. Attention: The user name and password are sent as base64-encoded text strings in the HTTP basic authentication header. To prevent eavesdropping, use only SSL secured connections by ensuring that the URL starts with https://. For more information, see RFC 2627.

271

Username token authentication

When using username token authentication in IBM BPM, a user name and password are passed to a web service in the SOAP header of the SOAP request. Username token authentication allows for different algorithms and formats for passing the password. IBM BPM supports passwords in plain text and digest format. The specification for username token authentication describes two optional elements that can be supplied: wsse:Noncewsu:Created The IBM BPM implementation of this standard always provides wsse:Nonce and wsu:Created. This is compatible with the behavior of Microsoft WSE 2.0 Toolkit when using username token digest authentication. For more information, see Web Services Security UsernameToken Profile 1.0.

Parent topic:Creating outbound integrations to web services Related information: Supported web service standards

272

Web service faults Faults are a way of handling exceptions in web services at run time. A fault that helps a user understand a problem and what he can do about it leads to a quick resolution of the problem. If you use a Web Service Integration step from the integration service palette to call an outbound web service, your step can catch and handle faults. To catch and handle faults, attach an error intermediate event to the web service integration. By default, configure the error intermediate event with the Catch All Errors option to catch faults which are modeled in WSDL, as well as other faults such as system or connectivity exceptions. For more information on handling faults, see Handling errors in services. Figure 1. An outbound web service integration with attached error intermediate

event If you want to catch specific WSDL faults (those that match a particular fault name or fault type), use the Catch Specific Errors option in the error intermediate event. Use the following requirements when you define the WSDL fault: - Specify a value for the name that begins with either an alphabetical character or the underscore (_) character. Valid values can include alphabetical characters, numbers, and the underscore. Names cannot contain words that are used within IBM Business Process Manager (for example, arrayOf or listOf). - When defining wsdl:part entries for the fault, use the element attribute in order to comply with the WS-I Basic Profile specification. The following example shows a web service that contains an error intermediate event that is set to catch specific WSDL errors, such as multiCFaultFault1. You can see the settings in the Error Properties section of Process Designer, as well as an excerpt of the related WSDL file.



273

After the web service integration discovers the WSDL file and generates the types (the input and output variables needed for the service), the specified faults can be caught when the web service runs.

Parent topic:Creating outbound integrations to web services Related information: Modeling events Handling errors in services

274

Serialization of IBM Business Process Manager objects for use in web services You can add metadata to IBM® BPM objects to control how those objects are serialized into XML elements in a SOAP request for web services. When sending complex types as input parameters to web services, IBM BPM often needs hints as to how to structure the data. These methods are built on the structure because a structure is, by definition, a Complex type. Note: Serializing IBM BPM objects for use in web services is primarily for advanced users, and is now required only when using Record objects with web services instead of the generated types. The following methods have been added to the tw.object.Record() object to assist in forming the SOAP request: - setSOAPElementName(string elementName) - setSOAPElementNS(string namespace) - defineSOAPProperty(string propertyName, string schemaName, string typeName, boolean isAttribute, string namespace)

Example You are passing an object of type NameUpdateRequest as an argument to a web service. This object is defined in the namespace http://www.lombardisoftware.com/schemas/NameUpdateRequest . The NameUpdateRequest object contains two properties, First (string) and Last (string). Following is example code to generate the XML that is part of the SOAP call:

This generates the following XML element: John Smith

Parent topic:Creating outbound integrations to web services

275

Setting up message-level encryption Message-level encryption provides confidentiality by applying encryption to all or parts of a SOAP message. The encryption spans the entire communication chain between the consumer and the provider. To take advantage of this type of encryption in integration services for BPDs, you must enable the corresponding configuration settings.

Before you begin There are two ways of setting up message-level encryption. You can use policy sets and bindings, which simplify the encryption with reusable configurations. To use policy sets and bindings, see the following topics: - Adding a web services server - Configuring a Web Service Integration component - Creating an inbound web service. Alternately, you can configure a specific encryption using the 100Custom.xml file as shown in this topic. First, check that the 100Custom.xml file exists. See The 99Local.xml and 100Custom.xml configuration files.

About this task The default 100Custom.xml configuration file includes a section that you can use to set up message-level encryption for integration services. teamworks.jks password soaprequester soaprequester password

soapprovider soapprovider JKS path to client certificate

Table 1. Elements in the section of the default 100Custom.xml file Element name

Description Provide a name for the key store file related to the service requester.

276

Example profile_root/etc/ws-

security/dsigsender.jks









Provide a key store password for the service requester. Holds an element that contains information about the private key for the client. This element has two child elements. Alias for the private key specified during creating of the key store. Holds the key name for the alias. If this element is not present, specify the alias name as the key name. Provide the encrypted key password for accessing the client private key. Provide the key store type. This element can have one of the following values:JKSUse this value if the keystore uses Java Keystore format.JCEKSUse this value if the Java Cryptography Extension is configured in the application server. PKCS12KS (PKCS12)Use this value if the keystore file uses the PKCS#12 file format. If a type is not provided, the default is JKS. Provide the client certificate path including the certificate file name.

KeyName : CN="Bob", OU=IBM, O=US,.. or KeyName : Bob

keystore-type="JKS"

{Install-Location}\client.cert

Procedure 1. Stop the deployment manager, process server, and Process Center server if they are running. 2. Open the 100Custom.xml file in a text editor. 3. Uncomment the section, and specify the encryption settings. 4. Specify the encryption settings. 5. Start the process server or the Process Center server.

Results

277

The encryption-related settings are now available for use in Process Designer for Web Service integration step types.

What to do next Specify the encryption settings on the Security tab for the Web Service integration step type. - Encrypt request - Select this option to encrypt outbound SOAP messages. Note that you cannot modify the parts of the message that are encrypted. The Web Service integration step type always encrypts the SOAP body, the WS-Security username token (if present), and the WS-Security signature (if present). With this option, you also need to provide a value for the Server certificate alias in order to configure the encryption key. - Expect encrypted response - Select this option to specify that you expect the web service provider to use WS-Security message-level encryption in the response. Note that you cannot modify the parts of the message that are encrypted. The Web Service integration step type always assumes that the SOAP body and the WS-Security signature (if present) are encrypted. With this option, you also need to provide a value for the Client certificate alias in order to configure the decryption key.

Parent topic:Creating outbound integrations to web services

278

Troubleshooting web servicesoutbound web service integrations Learn how to solve problems that you may have when using web service integration steps in your services. The following table describes some common problems that you might encounter when creating services that include web serviceoutbound web service integration steps: Table 1. Common problems for the outbound web service integrations Issue

Error message when you click Discover Incorrect WSDL URI value PARSER ERROR: Problem parsing '[path_name]\webAPIServi ce.':The markup in the document following the root element must be well formed.

Nonexistent host

Unknown Host Exception

279

Possible resolutions You have incorrectly typed the URI value. Navigate to the URI using a web browser to verify that you have the correct WSDL. A common problem is that the ?wsdl argument is missing from the end of the URI. For file protocol URIs, the URI does not exist on disk. If you are unable to validate the location of the URI on disk, contact your network administrator. You have incorrectly typed the host value. Navigate to the URI using a web browser to verify that you have the correct host information. The server that hosts the URI is offline (not running). Contact your network administrator to determine if this is causing the problem. The network is experiencing connectivity problems. Contact your network administrator to determine if this is causing the problem.

Authentication required for Runtime Exception: WSDL access Unauthorized access to '[path_name]\webAPIServi ce?WSDL'

The WSDL URI is protected by an authentication mechanism. If you have permission to access the web service, check the Protected WSDL check box, and then enter the Username and Password . Navigate to the WSDL URI using a web browser and save the text of the WSDL to a file so that you can use the file location as the target WSDL URI.

Parent topic:Creating outbound integrations to web services

280

Considerations when using WSDL with multiple XSD or WSDL imports When you are using Web Services Description Language (WSDL) with multiple XSD or WSDL imports for an outbound web service component, you can merge all of your XSDs into one WSDL file to avoid multiple connections to your endpoint. When you are using WSDL with multiple XSD or WSDL imports for an outbound web service component, IBM® BPM creates a connection for each XSD or WSDL import. For example, if you have 20 XSD imports defined in a WSDL file, IBM BPM creates 20 connections to your web service to fetch the artifacts. This happens in the following scenarios : 1. When you are discovering WSDL for the first time. 2. When you use web service integration for the first time after a server restart. 3. If the web service definition is not found in the IBM BPM runtime cache. To avoid multiple connections to your endpoint, you can merge all of your XSDs into one WSDL file. You can use a tool such as IBM Integration Designer (IID) to import your WSDL, and you can choose to include all of your XSDs in that WSDL file when you export the WSDL out of IID. Parent topic:Creating outbound integrations to web services

281

Troubleshooting XML schema messages for web service integrations When you are using a Web Service Integration component, you might encounter error and warning messages if you use XML constructs that are not supported or have problems in Process Designer. These errors and warnings occur when XML types that are not valid are generated for an external web service through a Web Service Integration component. You see these validation errors or warnings in the type generation panel of the Generate Types wizard, where you can copy them. The panel displays each error or warning and the exact line in the XML construct that is causing the problem. If an error occurs, you can select the Ignore problems and continue type generation to continue the type generation process. The following tables list the messages you could see in the wizard and information about each message.

Error messages caused by XML constructs that are not valid Message The {0} complex type contains the {1} element that has a type of anySimpleType, which is not supported.The {0} global element has a type of anySimpleType, which is not supported. The {0} complex type contains attribute {1} that is without a type or uses anySimpleType, which is not supported.

The {0} complex type contains anyAttribute. Attribute wildcards (anyAttribute) are not supported.

Description The anySimpleType type is not supported.To fix the error, replace anySimpleType with an appropriate simple type.

The type has an attribute declaration without a type definition, which defaults to anySimpleType or an attribute with anySimpleType. Attributes of anySimpleType are not supported. To fix the error, assign a simple type or replace anySimpleType with an appropriate simple type. Attribute wildcards permit an extension of the content model while providing some control to enforce a minimal constraint. Because wildcards are ignored,anyAttribute is not supported. The location of the wildcard is in XPath format.To fix the error, replace anyAttribute with an appropriate attribute.

282

The {0} complex type has a simpleContent child, which is not supported.

Complex types allow elements in their content to have a simple content element. Because simple content elements in a complex type are ignored, the simpleContent element is not supported. The {0} complex type contains Element wild cards, which allow an 'any' element . Element flexibility on what is allowed in wildcards (any) are not the content model, are not supported. supported.To fix the error, replace ANY with concrete elements. The {0} complex type contains The anyType type is not the {1} element that is directly or supported.To fix the error, indirectly mapped to anyType, replace anyType with an which is not supported.The {0} appropriate type. global element directly or indirectly maps to anyType, which is not supported. The {0} complex type contains a A model group definition group reference with maxOccurs associates a name with a model of {1}. However, the maximum group so that you can reuse the value of maxOccurs is 1. model group. However, Process Designer has a maximum occurrence constraint on the maxOccurs attribute in the model group definition.To fix the error, change the value of the maxOccurs attribute to 1. The {0} complex type contains Process Designer has a the {1} nested model group with maximum occurrence constraint a maxOccurs of {2}. However, on the maxOccurs attribute in the the maximum value of model group definition even if maxOccurs is 1. the model group is nested within other elements. To fix the error, change the value of the maxOccurs attribute in the identified model group to 1. The {0} simple type is not A union type creates a new type, handled. Union types are not which is the union of two or more supported. simple types. Union types are not supported.To fix the error, replace the union type with an appropriate simple type.

283

The {0} complex type extends the {1} complex type. However, the {1} type refers to xsi:type, which is not supported and might cause errors at run time.

If you use a derived complex type in place of a specified base complex type, it is assumed that a relationship exists between the base type definition and the derived type. The xsi:type annotations are ignored and only instances of the base complex type are created.

Warning message caused by XML constructs that have problems Message The {0} complex type contains the {1} attribute with a value of "default", which is not supported.The {0} complex type contains the {1} attribute with a value of "fixed", which is not supported. A type with name {0} already exists. Type names must be unique.

The {0} complex type contains the element {1} of the base64Binary type. The base64Binary type is transformed to String.The {0} global element is of the base64Binary type. The base64Binary type is transformed to String.The {0} complex type contains the element {1} of the hexBinary type. The hexBinary type is transformed to String.The {0} global element is of the hexBinary type. The hexBinary type is transformed to String.

Description Process Designer does not support attributes with default or fixed values. These values are ignored. To remove this warning, if no corresponding attribute is present in an instance document, specify a value for the attribute other than default or fixed. Process Designer does not support using qualified or QNames for types. The location of the type is in XPath format. Process Designer generates different names for these types. The base64Binary and hexBinary data types have validation rules that are supported in Process Designer. To prevent them from having values that are not valid in Process Designer, these data types are converted to strings.To remove this warning, do not use the base64Binary and hexBinary types.

284

The {0} complex type contains the element {1} of the gYear type. The gYear type is transformed to String.The {0} global element is of the gYeartype. The gYear type is transformed to String.The {0} complex type contains the element {1} of the gYearMonth type. The gYearMonth type is transformed to String.The {0} global element is of the gYearMonth type. The gYearMonth type is transformed to String. The {0} complex type contains the element {1} of the normalizedString type. The normalizedString type is transformed to String.The {0} global element is of the normalizedString type. The normalizedString type is transformed to String.

The gYear and gYearMonth data types have validation rules that are supported in Process Designer. To prevent them from having values that are not valid in Process Designer, these data types are converted to strings.To remove this warning, do not use the gYear and gYearMonth types.

The rules to normalize whitespace values are not supported in Process Designer. To prevent the types from having values that are not valid in Process Designer, their normalized strings are converted to strings.To remove this warning, do not use the normalizedString type. The {0} complex type contains All XML decimal numeric types, the element {1} of type {2}, which regardless of their precision, is transformed to Decimal. The transform to the Decimal type in Decimal type in Business IBM® BPM. The Decimal type Process Manager maps to maps to the java.lang.Double xsd:double.The {0} global data type through xsd:double. element is of the type {1} is transformed to Decimal. The Decimal type in Business Process Manager maps to xsd:double. The {0} complex type contains All XML integer numeric types, the element {1} of type {2}, which regardless of their precision, is transformed to Integer. transform to the Integer type in TheInteger type in Business IBM BPM. The Integer type Process Manager maps to maps to the xsd:int.The {0} global element java.lang.Integer data type is of the type {1}, which is through xsd:int. transformed to Integer. The Integer type in Business Process Manager maps to xsd:int. The {0} complex type extends When a complex type has a the {1} complex type. The base type, Process Designer generated business object for {0} includes all the elements and is flattened to include the attributes from the base type to elements and attributes that are flatten business objects that are defined in {1}. created from the complex type. 285

The {0} element contains the substitutionGroup attribute, which is not supported.

Substitution groups are ignored. With a substitution group, you can specify elements that can replace another element in documents generated from the schema. The {0} simple type contains the Process Designer ignores the {1} restriction facet, which is not following XSD restriction supported. facets:maxInclusivemaxExclus iveminInclusiveminExclusive enumeration

Parent topic:Creating outbound integrations to web services

286

Calling a Java method in an integration service If the implementation for an activity requires calling methods from a Java class, you can use the Java Integration step in an integration service.

Before you begin To perform this task, you must be in the IBM® Process Designer desktop editor. Before creating the Integration service, add the JAR file that contains the classes that you need. After you add the JAR file as a server file, you can select the class and method that you want to use for your service. If the JAR files that you need are included in an IBM Business Process Manager toolkit, you can add a dependency to that toolkit to access those files. See "Creating a toolkit dependency in the Designer view" for instructions.

Procedure 1. Open the Process Designer desktop editor. 2. Create an integration service. 3. Drag a Java Integration step from the palette to the service diagram and then use sequence lines to connect the step to the Start and End Events. 4. Click the Java Integration step in the diagram and then click the Definition option in the properties. 5. Click the Select button next to the Java Class field to choose the JAR file and the class on the JAR file that you want to call.The JAR files listed are the ones added as managed server files as described in topic "Managing external files". By default, the classes in the IBM BPM Java package are available in the integration.jar file, which is included in the System Data toolkit. If your current project has dependencies on other toolkits that include JAR files, those files are also available. 6. From the Discovery section (under the Properties and Definition tabs), click the Method field. From the drop-down list, choose the method that you want to call on the class that you selected in the preceding step. 7. Enable the Translate JavaBeans check box if you want the result of the Java method that is invoked to be serialized and returned to the Integration service as an XML element. The content of the element is based on the properties of the object's class. For example, if you choose the teamworks.Users class from the integration.jar file (IBM BPM Java packages) and then select the getUser method with the Translate JavaBeans check box enabled. The result looks like the following example: tw_author tw_author tw_author false true

287

Full Name tw_author 2 false false com.lombardisoftware.client.persistence.UserFactory 2048 false User LSW_USR_XREF tw_author

Note: When you enable the Translate JavaBeans check box, the variable type that you select in the Integration service for the value returned from the Java method should be XMLElement or ANY. If you do not enable the Translate JavaBeans check box, the Java method can only return objects of the types shown in Table 1. Table 1. Types of objects returned by the Java method if Translate JavaBeans is not enabled Object types java.lang.String java.lang.Long java.lang.Integer java.lang.Short java.lang.Byte

java.lang.Double java.lang.Float java.lang.Boolean java.lang.Character java.lang.Calendar

java.lang.ArrayList java.lang.HashMap org.jdom.Document org.jdom.Element com.lombardisoftwar e.core.XMLNodeList and com.lombardisoftwar e.core.TWObject

8. Click the Variables tab for the Integration service to add any input variables that the service needs to receive and any output variables that the service needs to make available for subsequent steps in the service or BPD. 9. Click the Java Integration step in the service diagram and then click the Data Mapping option in the properties to configure the input and output mappings for the step. 288

10. Nest the Integration service in another service or select it as the implementation for an activity, depending on the requirements of the overall process. Parent topic:Creating outbound integrations Related information: Creating, changing, and deleting a toolkit dependency in the Designer view Building an Integration service Managing external files Using the TWObjectFactory, TWObject and TWList classes

289

Sending attachments using an SMTP server With a Java Integration component, you can send attachments by using a Simple Mail Transfer Protocol (SMTP) server.

Before you begin To perform this task, you must be in the IBM® Process Designer desktop editor. Check that your system administrator set up the SMTP server. You must know its URL address when you complete the following procedure.

Procedure 1. Open the Process Designer desktop editor. 2. Create an integration service. 3. In the Integration service, add a Java Integration component. 4. In the Variables tab, add an input variable with a Boolean value set to true. The input variable instructs the SMTP server to use file names to identify attachments instead of a full path name. For example, use a name like useFileName. 5. Create all the other variables to pass values to the SMTP server. Use them later in the Data Mapping section. 6. On the Definition tab, select the teamworks.Mail class and the sendMessage method that includes the Boolean parameter. 7. In the Data Mapping section, add the variables that are expected by the SMTP server, including a variable for your attachments. In the Replace Full Paths By File Names field, add the variable that you created earlier to indicate that you are specifying the names of the files that are being transferred and that you are not using the full path name for them. Parent topic:Creating outbound integrations

290

Using IBM Business Process Manager SQL Integration services To integrate with an external database, you can use the SQL Integration services available in the IBM® BPM System Data Toolkit.

Before you begin To perform this task, you must be in the IBM Process Designer desktop editor.

About this task During IBM BPM installation, the System Data toolkit is imported into the Process Center repository so that each process application and toolkit that you create has access to IBM BPM system data. The System Data toolkit includes SQL Integration services to enable you to easily integrate with external databases. The SQL Integration services support common database interactions, including support for parameterized queries. In addition, these services can automatically map query results directly into the relevant variable type. The SQL Integration services enable you to develop implementations to: - Read existing data from a database - Update existing data in a database - Write new data to a database In addition, when passing data between IBM BPM and a connected database, the SQL Integration services enable you to specify certain types of data (like integers, BLOBs, and CLOBs). Important: The SQL connector services in the System Data toolkit support local transactions only. They do not work properly in global transactions, for example, during deployment or in an installation service. When SQL connector services are used in a scenario that requires a global transaction, you might receive an error similar to the following error:java.sql.SQLException: DSRA9350E: Operation Connection.commit is not allowed during a global transaction. at com.ibm.ws.rsadapter.jdbc.WSJdbcConnection.commit (WSJdbcConnection.java:1092) at teamworks.sql.SQLExecutor.executeInTransaction (SQLExecutor.java:111) at teamworks.SQLConnector.executeMultiple (SQLConnector.java:263)

The SQL Integration services are Java-based integrations that bind to a specific method in the teamworks.SQLConnector Java class. Although you cannot alter the SQL Integration services, you can open them in the Designer in IBM Process Designer to see the method implemented by each one and the available input and output variables as outlined in the following procedure.

Procedure

291

1. Open the Process Designer desktop editor. 2. Open a process application in the Designer view. 3. Click the indicator next to the Toolkits category to see a list of toolkit dependencies for the current process application. 4. Click the indicator next to the System Data toolkit to see its contents. 5. Click the Implementation category and then double-click one of the listed SQL services.For example, double-click the SQL Execute Statement service to open it. 6. In the service diagram, click the Java Integration component to select it. 7. Click the Definition option in the properties to display the Java Class and method implemented by the service. 8. Switch from the diagram view of the service by clicking the Variables tab. 9. Click an Input or Output variable to see its details, such as its type and default values (where applicable).

What to do next To use a SQL Integration service in an implementation, you can: - Select a SQL Integration service as the implementation for an activity as described in Implementing activities in a BPD . - Nest a SQL Integration service in another service by dragging it from the library to the diagram of the parent service.

Parent topic:Creating outbound integrations

292

Creating inbound integrations For inbound integrations that involve an external system or application calling into IBM® Business Process Manager to kick off a service, you need to build several IBM BPM components and corresponding services. See the following topics for instructions and more information: Note: You should also refer to Modeling message events to learn how to use a message event to represent a point in your process where an incoming message is received from an external system. - Building a sample inbound integration Several components must work together to complete an inbound integration. You can use the procedures listed in this topic to build and test a complete integration. - Creating implicit SOAP headers for inbound web service integrations SOAP headers are used to communicate application-specific context information within SOAP request and response messages. This context information can be anything that you must send along with the web service operation parameters. An implicit SOAP header is one that is not defined in the web service WSDL document. In an inbound web service integration, you can retrieve SOAP headers from an incoming request message and include SOAP headers in the outgoing response message. - Posting a message to IBM Business Process Manager Event Manager If you want to post a message from an external system to IBM BPM Event Manager, you must use the message structure that is described in this topic. - Publishing IBM Business Process Manager web services IBM BPM can publish web services in the same way that it consumes web services. Using a SOAP connection, external applications can call the IBM BPM web service to initiate a particular service or set of services. Parent topic:Integrating with web services, Java and databases Related information: Undercover agents

293

Building a sample inbound integration Several components must work together to complete an inbound integration. You can use the procedures listed in this topic to build and test a complete integration. To implement an inbound integration in IBM® Business Process Manager, you need to build several components that work together. The following image represents the steps required to build a sample inbound integration. Figure 1. Steps to build a sample inbound integration

For general and introductory information, see Integrating with web services, Java and databases. The following sections describe how to create simple components so that you can easily build the integration and also easily test your initial implementation. References to more detailed descriptions of the implementation options for each component are provided in the relevant sections. Note: You can call an undercover agent (UCA) using another business process definition (BPD), using a web service (and an associated caller service), or via JMS as illustrated in this sample. To learn how to establish message flow between two BPDs instead of using a service, see Using intermediate message events and message end events to send messages and Using message end events. - Adding a message event to a BPD Start building the sample integration by adding a message event to a business process definition (BPD). - Creating an attached service Create a service to pass parameter values from the message event to the business process definition (BPD). - Creating an undercover agent Create an event-based undercover agent. - Attaching the undercover agent to the message event Attach the undercover agent (UCA) to the message event. The event waits for the completion of the UCA. When the UCA completes, the event completes. - Creating a caller service Create a service with appropriate inputs to call the undercover agent (UCA) to send the event. - Creating an inbound web service Create an inbound web service to provide a way for an external system or application to call into IBM Business Process Manager. - Testing the integration Test the completed inbound integration using the Inspector. Parent topic:Creating inbound integrations

294

Adding a message event to a BPD Start building the sample integration by adding a message event to a business process definition (BPD).

Before you begin To perform this task, you must be in the IBM® Process Designer desktop editor.

Procedure 1. Open the Process Designer desktop editor. 2. Open a process application in the Designer view. 3. Create a simple BPD that contains two activities. (If you need detailed instructions, see Creating a business process definition (BPD) .) 4. Drag an Intermediate Event component from the palette onto the BPD diagram so that it falls between the two activities. 5. In the text box that displays over the event, type a name for the event. For this sample, you can type: Incoming Message Event. 6. Click the Implementation tab in the properties. The default implementation for intermediate events that are included in the process flow is Message. 7. If not already selected, click the drop-down list and choose Receiving from the available message types. 8. Use the Sequence Flow tool to connect the BPD components as shown in the

following example: 9. Save your work. Parent topic:Building a sample inbound integration

295

Creating an attached service Create a service to pass parameter values from the message event to the business process definition (BPD).

Before you begin To perform this task, you must be in the IBM® Process Designer desktop editor.

About this task The undercover agent (UCA) that you attach to the message event needs a service to pass the parameter values from the runtime message to the BPD. Note: For intermediate message events like the one in this sample inbound integration, even if no parameter values are being passed from the message event to the BPD, you must map a UCA input variable to a local variable to ensure that the correct running instance of the BPD resumes execution upon receipt of the message event.

Procedure 1. Open the Process Designer desktop editor. 2. Open a process application that contains a BPD. 3. Create a General System service and name it My UCA Handler or something similar. (If you need detailed instructions, see Building a General System service .) 4. Use the Sequence Flow tool to connect the Start Event and End Event components in the service diagram. Because this service is used to simply pass values, you do not need to add any service components to the diagram. 5. Click the Variables tab. 6. Click the Add Input button and replace Untitled in the Name field with someString. 7. Leave the variable type for the input variable set to String. 8. Click the Add Output button and replace Untitled in the Name field with someString. 9. Leave the variable type for the output variable set to String. 10. Save your work. Parent topic:Building a sample inbound integration

296

Creating an undercover agent Create an event-based undercover agent.

Before you begin To perform this task, you must be in the IBM® Process Designer desktop editor.

About this task The undercover agent tells IBM Business Process Manager what service to run when the message event is received. The message can be triggered by IBM BPM itself or by an external system as in this example.

Procedure 1. Open the Process Designer desktop editor. 2. Open a process application in the Designer view. 3. Click the plus sign next to Implementation and then select Undercover Agent from the list. 4. In New Undercover Agent, enter the following information and then click the Finish button. - Name: Type My UCA or something similar for the name. - Schedule Type: Select On Event from the drop-down list. 5. In the Details section, the queue for processing this undercover agent is set to Async Queue by default. This setting is fine for the sample integration. (To learn more about the queue options, see Undercover agents.) 6. In the Parameter Mapping section, you can see that the undercover agent is automatically mapped to the someString variable from the attached service, My UCA Handler. 7. Save your work.

What to do next Now that the undercover agent is available, you can attach it to the message event. Parent topic:Building a sample inbound integration Related information: Undercover agents

297

Attaching the undercover agent to the message event Attach the undercover agent (UCA) to the message event. The event waits for the completion of the UCA. When the UCA completes, the event completes.

Before you begin To perform this task, you must be in the IBM® Process Designer desktop editor.

About this task After you create the UCA, you should go back to the message event in the BPD and attach the UCA as described in the following steps.

Procedure 1. 2. 3. 4. 5. 6.

Open the Process Designer desktop editor. Open a process application that contains a BPD with a message event. Open the BPD that includes the message event. Click the message event in the BPD to select it. Click the Implementation option in the properties. In the Message Trigger section, click the Select button next to the Attached UCA field and pick My UCA that you created in the preceding steps. 7. Ensure that the Consume Message and Durable Subscription check boxes are enabled. (For more information about these options, see Modeling message events.)Tip: If you occasionally use inbound messages, consider using durable subscription events. Durable subscriptions are Java Message Service (JMS) subscriptions that persist and store subscribed messages even when the client is not connected. The durable messages accumulate, even if you select the check box to make them consumable. Periodically use the BPMDeleteDurableMessages command for deleting durable subscription events. 8. Click the Data Mapping option in the properties. Notice that the Output correlation key is automatically set to the someString variable from the UCA. The variable is used as a correlation parameter, which allows you to correlate an event recipient with a particular key. Note: When an event occurs, that event must be matched against the correct instance of the process for which the event is destined. The ability to match the event against the correct instance is called correlation. You must specify one variable in the message event that has a value that matches the value of the incoming event's UCA payload (the correlation value). If there is such a match, the message is received. If not, the message is not received, and the event continues to wait. 9. In the field next to the variable, type tw.system.process.instanceId. This sets the value of the someString variable to the ID of the running instance, which allows you to test the implementation in the Inspector.In this example, you are creating a UCA that uses the current process instance ID as the correlation parameter. For example, if you have a process application with the instance ID

298

of 50 and another process application with the instance ID of 100, if you invoke the UCA passing an ID of 50, only the first process application receives the event. 10. Save your work. Parent topic:Building a sample inbound integration Related information: Undercover agents

299

Creating a caller service Create a service with appropriate inputs to call the undercover agent (UCA) to send the event.

Before you begin To perform this task, you must be in the IBM® Process Designer desktop editor.

About this task The next step in completing this sample inbound integration is to create an Integration service to call the UCA to send the event when the inbound web service (that you create in the following section) is called.

Procedure 1. Open the Process Designer desktop editor. 2. Open a process application in the Designer view. 3. Create an Integration service and name it Inbound WS Handler or something similar. (If you need detailed instructions, see Building an Integration service.) 4. Drag an Invoke UCA component from the palette, name it My UCA and place it between the Start Event and End Event in the service diagram. 5. Use the Sequence Flow tool to connect the service components on the diagram. 6. Click the Invoke UCA component in the diagram. 7. Click the Variables tab, and then click the Add Input button to add the someString variable as an input variable. 8. Save the changes. 9. Select the Implementation option in the properties. 10. Click the Select button next to the Attached Undercover Agent field and pick the Undercover Agent that you created in the preceding procedure, My UCA. 11. Select the Data Mapping option in the properties. The Input Mapping is automatically set to the someString variable from the UCA. 12. In the field next to the variable, type tw.local.someString. This sets the input value of the UCA to the local value of the someString variable, which enables you to test the implementation in the Inspector as instructed in Testing the integration. The value is used in the business process definition correlation mapping that is created in the initial task. Note: The someString variable is available only if you create the attached service as instructed in Creating an attached service and the UCA as instructed in Creating an undercover agent before performing the steps in this procedure. 13. Save your work. Parent topic:Building a sample inbound integration

300

Creating an inbound web service Create an inbound web service to provide a way for an external system or application to call into IBM® Business Process Manager.

Before you begin To perform this task, you must be in the IBM Process Designer desktop editor.

About this task Now you need to provide a way for an external system or application to call into IBM Business Process Manager. The recommended method for accomplishing this is to create and publish a web service endpoint so that external applications can initiate a particular IBM BPM service or set of services by invoking an operation on the endpoint. By invoking a SOAP call, external applications can call the web service. All operations that are exposed on an inbound web service are exposed as requestresponse operations. Even an operation bound to a service that has no outputs will be exposed as a request-response operation with no output. One-way operations are not supported. Tip: The endpoint address for a web service is in the following format: http:// host_name:port/[custom_prefix/]teamworks/webservices/process_app_name/[ snapshot_name/]web_service_name.tws. If you do not specify the snapshot_name in

the endpoint URL, it points to the tip snapshot for Process Center, or to the default snapshot for Process Server. If you want to invoke a web service for a specific snapshot, make sure to specify the snapshot_name in the endpoint URL.

Procedure 1. Open the Process Designer desktop editor. 2. Open a process application in the Designer view. 3. Select the plus sign next to the Implementation category and then select Web Service from the list. 4. In New Web Service, type KickTheBPD in the Name field and then click the Finish button. 5. In the Operations section, click the Add button and select the Inbound WS Handler Integration service that you created in the preceding procedure from the list. 6. In the Operation Detail section, change Untitled in the Operation Name field to doKick or something similar. 7. Notice the WSDL URI in the Behavior section. You can use this URI to test the sample integration as instructed in Testing the integration.The Protected check box adds user name and password security to an operation in the web service. For a web service client to invoke a protected operation, the user ID and password added to the user name and password elements for this operation must be registered at the server, assigned to the process application and have at least

301

read authority. Note that this is not authentication in the context of an HTTP transaction, so selecting Protected does not display a default user ID and password. The Target namespace scheme drop-down list provides options for setting the target namespace: - Per Process App/Toolkit settings (default): Uses the namespace from the Advanced XML Settings section of the Process App Settings page and does not include the snapshot name. This is the recommended setting as the target namespace will remain consistent when using multiple snapshots. Note that the namespace must be already set at the time of this selection or Per snapshot name will be used. You will not be able to modify or update this value. - Per snapshot name: Includes the snapshot name as well as the namespace from the Advanced XML Settings section of the Process App Settings page, if set. This scheme was used to define the target namespace before IBM BPM 8.0.1. The target namespace value in your web service client will be different each time a snapshot is taken. You will not be able to modify or update this value. - Custom: Lets you create your own target namespace in the Target namespace field. Important: If you select Per snapshot name, the namespace of the Web Services Description Language (WSDL) file will be changed in the following cases. You must generate the types again for your inbound web service so that your namespace is consistent with the namespace on the server. - The inbound web service uses a business object defined in the System Data toolkit. The namespace of that business object uses a host name and port specification. You must generate the types again if the inbound web service's host name and port are changed because of this situation. - The Target namespace schema field is changed to the Per snapshot name value. The namespace of the WSDL file will use the snapshot name once you select this option. You must generate the types again for your inbound web service each time you create a snapshot. - The Target namespace schema field is changed to the Per snapshot name value. The namespace of the WSDL file will use the snapshot name once you select this option. You must generate the types again for your inbound web service each time you switch the snapshot to the default or the non-default version. Note: In this situation, if the inbound web service is defined in the toolkit, the namespace of this WSDL file will not be changed when you switch the snapshot to the default or the non-default version. 8. The Security and Policy section allows you to configure a policy set and a policy binding with your web service. The server must have been already configured by a system administrator. - Policy Set: Specifies the name of the application policy set. Click Select to choose the policy set. The list you will see depends on the policies available on the server. Some default application policy sets include: WSHTTPS default, WSAddressing default, and Username WSSecurity default. You can also create additional application policy sets in the WebSphere Application Server 302

Administrative Console. Deselecting a policy set also removes the policy binding. More information on policy sets can be found in the IBM Redbook WebSphere Application Server Web Services Guide. - Policy Binding: Specifies the name of the general provider policy set binding, which contains system-specific configuration parameters like username and password information. Click Select to choose the policy binding. The list you will see depends on the general provider policy set bindings available on the server. Default policy set bindings include: Provider sample and Provider sample V2. You can also create additional policy set bindings in the WebSphere Application Server Administrative Console. Deselecting removes the policy binding. Note: SOAP header information is available in system variables. The tw.system.soap.header.request variable is automatically initialized to contain the list of SOAP header entries found in the incoming request message. You can include JavaScript code with your inbound web service which accesses these SOAP header entries. You can also write JavaScript code which adds SOAP header entries to the tw.system.soap.header.response system variable. The SOAP header entries contained in this variable are added to the outbound response message. 9. Save your work.Limitation: Any variable with a simple type containing a restriction element will not have the restriction element on generation of the inbound web service.

What to do next If you do not specify a snapshot name in the URI, then the default track is used to locate your web service. The tip in the default track is assumed to contain the process application with your web service. However, if you have your web service on a tip in a non-default track, it cannot be found. Therefore, create a snapshot name or make the track that you are working with the default track.

Parent topic:Building a sample inbound integration Related information: Supported web service standards

303

Testing the integration Test the completed inbound integration using the Inspector.

Before you begin To perform this task, you must be in the IBM® Process Designer desktop editor.

About this task After you build and link the input and output of the required components as instructed in the preceding procedures, you can test the completed inbound integration using the Inspector in IBM Process Designer and a utility such as soapUI.

Procedure 1. Open the Process Designer desktop editor. 2. Open a process application that contains the simple BPD that you created per the instructions in Adding a message event to a BPD. 3. Open the BPD and click the Run icon in the upper right corner of the BPD diagram. (If you need detailed instructions for using the Inspector, see Stepping through a process.) 4. When IBM Business Process Manager prompts you to change to the Inspector interface, click Yes. Note: Click the check box if you want IBM Process Designer to change interfaces without prompting for approval. 5. From the Process Instances tab, click the received task for Step 1 and then click the run icon ( ). The coach for the activity, which is the default Human service, opens in a browser. 6. Click the Done button in the Coach to complete the first step. 7. Click the refresh icon ( ) in the toolbar. You can see that the process instance is waiting for the incoming message event. 8. Using your SOAP utility, such as soapUI, point to the WSDL URI for the KickTheBPD inbound web service that you created per the instructions in Creating an inbound web service. 9. In your SOAP utility, initiate a request to the doKick method. In the someString parameter for the method, provide the Instance ID for the currently active instance, which you can see in the Process Instances tab in the Inspector. For example, in the preceding image, the instance ID of the active instance is 4. 10. Click the Refresh icon in the Inspector toolbar. You should see that Step 2 has been received, meaning that the message event was successfully processed and the instance is able to move to the next step. 11. Click the Step 2 task to select it and then click the Run task icon. The value is used in the business process definition correlation mapping that is created in the initial task. If this value and the value of the BPD mapped variable are equal, the message intermediate start event runs. If not, the message intermediate start event continues to wait until a match is found.

304

12. The Coach for the activity, which is the default Human service, opens in a browser. Click the Done button in the Coach to complete the second step. 13. Click the Refresh icon in the Inspector toolbar. You should see that the task for Step 2 is closed and the process instance has a status of Complete, indicating that the BPD instance has completed successfully. Parent topic:Building a sample inbound integration

305

Creating implicit SOAP headers for inbound web service integrations SOAP headers are used to communicate application-specific context information within SOAP request and response messages. This context information can be anything that you must send along with the web service operation parameters. An implicit SOAP header is one that is not defined in the web service WSDL document. In an inbound web service integration, you can retrieve SOAP headers from an incoming request message and include SOAP headers in the outgoing response message. - Retrieving SOAP headers from an inbound request message You can retrieve SOAP headers from an inbound request message by writing some JavaScript code to capture data from the tw.system.header.soap.request system variable. - Adding SOAP headers to an outgoing response message You can add a SOAP header to an outbound response message by using a system variable and some JavaScript code. Parent topic:Creating inbound integrations

306

Retrieving SOAP headers from an inbound request message You can retrieve SOAP headers from an inbound request message by writing some JavaScript code to capture data from the tw.system.header.soap.request system variable.

Before you begin This task requires that you have access to an inbound web service integration that has at least one general system service associated with it.

About this task IBM® Business Process Manager provides a system variable that you can use to retrieve SOAP headers. SOAP headers found in inbound request messages are automatically copied to the tw.system.header.soap.request system variable. You can write code to retrieve those SOAP headers.

Procedure To retrieve SOAP headers from an inbound SOAP request message, write JavaScript code that uses the tw.system.header.soap.request system variable. You can add a component, such as a server script component, to your general system service. You can then add your JavaScript code to this component's Properties view within the Pre-execution or Post-execution Assignments section or within the Implementation section. Alternatively, you can add the code to any location that is part of the general system service for the endpoint. In this example, the code example is retrieving a header named subscriptionInfo of type SOAPHeader from the system variable tw.system.header.soap.request. If the request message contains SOAP headers, this variable will be initialized to contain them. If the request message does not contain SOAP headers, this variable will be null. log.info(">>>>>> Checking to see if the subscriptionInfo SOAP header was received in the request message...")

var subscriptionInfoHeader = null

if (tw.system.header.soap.request != null) { for (var i = 0; i < tw.system.header.soap.request.headers.listLength; i++) { // search for the subscriptionInfo header if (tw.system.header.soap.request.headers[i].name == "subscriptionInfo") { subscriptionInfoHeader = tw.system.header.soap.request.headers[i] } } }

if (subscriptionInfoHeader != null) { log.info("Found the subscriptionInfo SOAP header!") }

307

else { log.info("The subscriptionInfo SOAP header was not present in the request message.") }

Assume that the following SOAP header is in a request message:1234-56-7890-fc3a

The following output is produced by the code in that example: Found

the subscriptionInfo SOAP

header!

Parent topic:Creating implicit SOAP headers for inbound web service integrations

308

Adding SOAP headers to an outgoing response message You can add a SOAP header to an outbound response message by using a system variable and some JavaScript code.

About this task IBM® Business Process Manager provides a system variable that allows you to add SOAP headers to an outbound response message, tw.system.header.soap.response. You can instantiate the tw.system.header.soap.response variable from the Variables tab above the process diagram or in the JavaScript code.

Procedure To add a SOAP header to an outbound response message, add an entry to the SOAPHeaders array within the tw.system.header.soap.response system variable. You can add the code to the Pre & Post > Post-execution Assignments section within a component of a general system service, such as a server script component. To add a header that is called sessionToken to the response message, use JavaScript code such as the following example. Follow these best practices as you write your code: - Make sure namespaces are fully qualified, as they are in the following examples. - Avoid white spaces in the XML snippet that constitutes the SOAP header value. - Make sure that you only instantiate the tw.system.header.soap.response variable if it is null. Otherwise, you could end up clearing out SOAP header entries that were added by some other component within your general system service. log.info(">>>>>> Adding a SOAP header to the response message...")

// Create the header object var myResponseHeader = new tw.object.SOAPHeader() myResponseHeader.name = "sessionToken" myResponseHeader.nameSpace = "http://acme.com" myResponseHeader.value = "abdf-128974-33-33-fcea-10243-7433"

// If the response header system variable doesn't exist yet, // then you must instantiate it if (tw.system.header.soap.response == null) { tw.system.header.soap.response = new tw.object.SOAPHeaders() tw.system.header.soap.response.headers = new Array() }

// Determine which index we need to use when adding the new header entry. //Add the new header at the end of the array so that the processing does not // overwrite any existing entries. var nextIndex = tw.system.header.soap.response.headers.listLength

309

log.info("Adding new header at index: " + nextIndex) tw.system.header.soap.response.headers[nextIndex] = myResponseHeader

Note: Use the next available index when adding your new SOAP header entry to the tw.system.header.soap.response variable "headers" field, which is an array of SOAP header values. Otherwise, you might inadvertently clear out an existing SOAP header entry that was added by some other component within your general system service.

Parent topic:Creating implicit SOAP headers for inbound web service integrations

310

Posting a message to IBM Business Process Manager Event Manager If you want to post a message from an external system to IBM® BPM Event Manager, you must use the message structure that is described in this topic. You can use Java Message Service (JMS) to post a message to the Event Manager. See Maintaining and monitoring IBM Business Process Manager Event Manager to learn how the Event Manager processes incoming requests.

Understanding the message structure The message that you post to the Event Manager must contain an event name (the message event ID generated when you create an undercover agent) and it can contain parameter names and values in key-value pairs. (The topic Creating and configuring an undercover agent for a message event describes the message event ID that you should use for the event name.) The message must be structured as XML as shown in the following example: [event_name] [queue name]

true



true

debug

891



Parent topic:Running and debugging processes with the Inspector

892

Stepping through a process Step through process execution to ensure that your BPD works as expected.

About this task When you run a process, you can step through the execution to ensure that your business process definition works as expected. You can use this functionality for team playbacks and to help debug your process. Note: To learn more about the Inspector interface before you begin, see Inspector reference.

Procedure 1. Open a business process definition in IBM® Process Designer. 2. Optional: To view instances running on a different server or to view instances for a different version of the BPD, select a different server or snapshot from the drop-down menus in the toolbar.Important: Remote Process Servers must be connected to your Process Center to be available. To learn how to connect to remote Process Servers, see Using wsadmin commands to customize the Process Server settings used to connect to Process Center in IBM Business Process Manager and Using the administrative console to customize the Process Server settings used to connect to Process Center. To run a process on a different server using the Inspector, you must first deploy the process application snapshot that contains the process that you want to run as described in Installing snapshots on a connected process server. If you click the Run icon while All versions is selected from the list of snapshots, the Inspector runs the most recent snapshot of the BPD on the Process Center Server. For remote Process Servers, the snapshots available are limited to the snapshots that are deployed on that server. 3. Click the Run button in the upper right corner. 4. When IBM Business Process Manager prompts you to change to the Inspector interface, click Yes.Note: Select the check box if you want IBM Process Designer to change interfaces without prompting for approval. 5. In the Process Instances tab, click the new or received task and then click the Run button. In some cases, you might need to select a user account or provide a password for a specific user account in order to run a task. This is controlled by lane assignments and routing for activities. See Assigning teams to BPDs and lanes and Assigning teams to BPD activities for more information. 6. Complete the task when it runs. For example, if the task generates a Coach, enter requested values and complete the form. When the task is complete, you return to the Inspector. 7. Click the Refresh icon in the toolbar. The Inspector shows the progress by moving the token to the next step in both the diagram and the navigation tree. Note: If your BPD includes an attached timer event, you can right-click the timer event token in the navigation tree and select Fire Timer to trigger the event. 8. You can expand subprocesses, event subprocesses, and linked processes as you step through their contents by double-clicking on the activity in the diagram

893

view. Even if you do not expand a subprocess activity, you still step through activities contained in the subprocess. 9. To see the variables passed from step to step, click the process node in the navigation tree. 10. Right-click a variable and then click Show in Execution Evaluator. The Inspector opens the Execution Evaluator tab and shows the values for the parameters within the selected variable. You can use the Execution Evaluator to inspect the variable values as they change through the flow of the business process definition. Note: You can also manipulate variables in the Execution Evaluator using JavaScript expressions to validate your process implementation. To do so, enter the JavaScript expression and click the Run icon at the top of the Evaluator. The results are displayed in the bottom pane of the tab. 11. In the Process Instances tab, click the task for the next step, and then click the Run task icon. 12. Click the Refresh icon in the toolbar. You can tell that the business process definition is complete when the final step has a status of Closed and there are no active tokens in the diagram or navigation tree. Parent topic:Running and debugging processes with the Inspector

894

Debugging a process Use the Inspector debugging feature to examine each underlying process or service in each step of your process execution to perform a more thorough inspection than stepping through your process.

About this task The Inspector executes a debugging session in a browser window. As you step through an underlying process or service in the debug session in your browser, the Inspector interface shows the same progress in its diagram view and navigation tree. You can use the information from the debugging process to help identify the point at which a process instance is not functioning as expected. Note: To learn more about the Inspector interface before you begin, see Inspector reference.

Procedure 1. Open a business process definition (BPD) in IBM® Process Designer. 2. Click Run. 3. When IBM Business Process Manager prompts you to change to the Inspector perspective, click Yes.Note: Select the check box if you want IBM Process Designer to change interfaces without prompting for approval. 4. In the Process Instances tab, click the new task, and then click Debug task. Depending on the task implementation, complete the steps in one of the following procedures: - If the task that you are debugging is implemented as a client-side human service, the client-side human service Inspector opens in a browser window, pausing on the first step after the Start event. Complete the following steps to debug the client-side human service: A. When prompted, select the user that you want to debug the client-side human service as. You can choose to debug the service as the user that claimed the task or as a different user. For a different user, the user name that you select must belong to a user group that has read access to the corresponding process application. You are logged in to the web browser using the selected user name. B. Use the actions on the sidebar to proceed with the debugging of the clientside human service. See Debugging client-side human services. C. Before running each step in the service flow, examine the variable values that are displayed on the sidebar at each point to determine whether they are expected. D. To move to the next activity in the service flow, click Step Over . E. If this activity is a coach, complete the coach and trigger the boundary event to transition out of the coach. The Inspector moves to the next step in the service flow.

895

F. (Optional) To view the progress of the service execution, you can click the Designer tab in the upper-left corner of the browser window. On the clientside human service diagram, the followed path is highlighted and a colorcoded token marks the current position in the service flow. G. Complete the debugging of the client-side human service in the Inspector browser window. H. When the debugging of the client-side human service is complete, go back to the BPD Inspector window and click Refresh to update the task status accordingly. The Inspector moves to the next step in the process flow. At the same time, the Inspector shows progress through the service, using tokens in the diagram and navigation tree. - If the task that you are debugging is not implemented as a client-side human service, complete the following steps to debug the service: A. If the service does not require user input, click Run to run all code and logic and then view the end values. B. If the service requires user input, use the Step button and complete the fields for any associated coaches to step through each part of the service. The BPD Inspector opens a debugging session in a browser window. At the same time, the Inspector opens the currently executing service in the Services in Debug tab and shows progress through the service, using tokens in the diagram and navigation tree. 5. To continue through the rest of your BPD, click the Process Instances tab in the Inspector, and then repeat the actions in step 4. In the debugger session in your browser, you can see data that you enter into any displayed coaches and the values that cause the underlying logic in the services and BPD to proceed along the available paths. This insight can be extremely helpful when issues are identified and you need to find the point at which a process instance is not functioning as you expected. Parent topic:Running and debugging processes with the Inspector

896

Resolving errors Find the source of errors generated when running your business process definition (BPD) and resolve them.

About this task When you run a process or a service and an exception occurs in the instance, the Inspector clearly identifies the error in the diagram and navigation tree. The Inspector also: - Tells you exactly where the error happened - Links directly to the source of the problem The following steps describe how the Inspector identifies an error in a running instance and how it helps you resolve the error:

Procedure 1. When the execution of a BPD does not complete successfully, the Inspector displays the error in the BPD diagram and also in the navigation tree. 2. Click the error shown in the navigation tree to open the Runtime Error Information window. The Runtime Error Information window indicates where the error happened and it also provides a link to the service in which the error occurred so you can go directly to the source. 3. Click More in the Runtime Error Information window to show additional details about the error, such as stack trace details. You can also use the Copy to Clipboard button if you want to paste the contents of the window to a text file or support ticket. The Inspector copies all information to the clipboard, including stack traces. Parent topic:Running and debugging processes with the Inspector

897

Inspector reference Learn how to access and use each feature provided by the Inspector. The following image shows the Inspector interface and each major functional area:

The following table describes each numbered area in the preceding image of the Inspector interface in IBM® Process Designer: Table 1. Description of numbered areas on the Inspector interface image Area number 1

2

Description Shows the currently active and previously run process instances on the Process Center Server or connected Process Server in the Process Instances tab. The highlighted instance is the currently selected instance, which means any action you perform or any data shown in the other areas of the Inspector apply to this instance. (The Services in Debug tab becomes active only if you select the Debug icon for a particular task.) Use the Instance Name field and the Status drop-down menu to control the list of instances displayed in the Process Instances tab. For example, if you want to see only active process instances that include the word employee in their name, type employee in the Instance Name field and select Active from the Status dropdown menu.

898

3

4

5

Use the drop-down lists to choose a different server on which to run the current BPD. You can also choose a different snapshot if you want to run a different version of the BPD. The Process Instances tab includes a Snapshot column so that you know which version of a process the currently displayed instances are running. For example, in the preceding image, the Snapshot column displays Tip to indicate that you are running the version of the process currently under development in the Designer. Remote Process Servers must be connected to your Process Center to be available. To learn how to connect runtime process servers to the Process Center, see Using wsadmin commands to customize the Process Server settings used to connect to Process Center in IBM Business Process Manager and Using the administrative console to customize the Process Server settings used to connect to Process Center. To run a process on a different server using the Inspector, you must first deploy the process application snapshot that contains the process that you want to run as described in Installing snapshots on a connected process server. Note: When you change servers or versions in the Inspector, you have to start the BPD again by choosing the run icon at the upper right of the BPD diagram. Use the icons in the toolbar to manage process instances, run tasks, or debug services. For more information, see Inspector toolbar options. Shows the current task for the selected process instance. In the preceding example, the current task is the first task in the BPD called Submit job requisition. You can click the task to select it and then use the toolbar icon to run the task so that you can step through the entire BPD.

899

6

7

8

9

Shows the BPD diagram for the selected instance and highlights the current task so you know where you are in the execution of the process for this instance. In the preceding example, the red token above and the yellow halo around the Submit job requisition task indicate the active step. If you want to view other information about the BPD for the selected instance, you can click the other available tabs such as Overview and Variables. Shows a navigation tree of the execution progress for the selected instance. In the preceding example, you can see the first step in the instance (the start of the process) and you can see the active second step, indicated by the red token. The navigation tree continues to expand if you decide to run the task and step through the entire process in the Inspector. Shows the variables used in the current step. In the preceding example, we can see that the requisition variable is used in the active step. You can select a variable, right-click, and then select Show In Execution Evaluator to view and manipulate the variable values. Use the drop-down menu to change the Inspector interface display. When you open the Inspector interface, you see the Standard display which is described in the preceding rows. You can choose to show less information (Simple) or more (Edit & Debug).

Inspector toolbar options When viewing instances of processes in the Process Instances tab of the Inspector, the following toolbar icons are available to help you manage those instances. Table 2. Toolbar icons available on the Process Instances tab Toolbar icon

Function Pauses the selected process instance. Resumes a suspended process instance. Stops a running process instance. Removes any record of the selected process instance.

900

Refreshes the current list of process instances based on the filter you have selected and the most recent data from the Process Server. When stepping through a process instance, you need to click Refresh after completing a step so that the diagram view and navigation tree properly display your progress. Pages through the BPD instances when more than 100 instances are displayed in the Process Instances tab. Runs the selected task. A web browser opens to display coach(es), while the Inspector displays red tokens both in the BPD diagram and the navigation tree of the execution state to show the step that is executing in the active process instance. Opens a debug session in your default web browser for the selected task. The debug feature enables you to step through each service in each stage of the process execution to view the business data that is passed in and out. As you step through a service in the debug session in your browser, the Inspector interface shows the same progress in the currently executing service in the diagram view and navigation tree. Opens the Details user interface for the selected process instance in Process Portal in your default web browser. You can test the interaction between the user interface and the process.

Understanding tokens In the Inspector interface, tokens indicate where the runtime instance is currently executing-both in the diagram of the BPD or service and in the navigation tree of the instance execution. The following general rules apply to tokens: - If a token is on a step, that step is in an active state. Until the step has been completed, the process instance cannot proceed. - If a token is on a conditional sequence flow, the target step is enabled-it can receive the token-because the condition on the sequence flow was met. Conditions are evaluated after the step has been completed but before the process enters the outgoing sequence flow. - A process instance can generate several tokens. For example, a split can cause two tokens to be generated. These tokens are merged into a single token when the process reaches a join gateway.

901

Parent topic:Running and debugging processes with the Inspector

902

Authentication during playback to handle changes in user identity Process applications can use Process Designer capabilities that you can access only from your locally installed Process Designer and some capabilities that you can access only on the web. This topic describes the behavior that occurs when you have an artifact open in the web browser and you do a playback from within the Process Designer installed locally on your computer.

About this task When you start the playback session, the playback window opens in the default browser window for Process Designer. The following actions occur: - When you claim a task that is currently assigned to a team that you belong to, you are prompted to select the user name that you will run the task as. You can choose to run the task as the logged-in user or as a different user. The logged-in user is selected by default. - The task is run in a web browser and you are logged in to the web browser using the selected user name. - If you select a different user name, ensure that the different user belongs to a user group that has read or write access to that process application. - If a playback action is performed using a different user name, you are notified that you will be logged out of your browser session to allow you to complete the playback action as the different user. - After the playback action is complete, you are prompted to log back in to the web browser. Depending on what artifact you are working with, different actions can trigger this behavior. For example, you can encounter the described behavior when you perform either one of the following actions: - Click Run to claim a business process definition (BPD) task instance. - Open a heritage human service in the Process Designer editor and click Run Service to test it in a playback session. - Right-click a human service or a heritage human service and select Playback > Run Service to launch the playback session.

Parent topic:Testing and debugging process applications

903

Globalization To ensure that applications can be used in multiple geographical locations and cultures, globalization support is built in through appropriate design and implementation of systems, software, and procedures. IBM® Business Process Manager provides globalization support for single- and multi-byte character sets and for bidirectional transformation including contextual support, support for text layout transformation, and calendar support for Hebrew and Hijri. For more information about using translated IBM Business Process Manager components, see Known issues for translated IBM BPM components. - Bidirectional support in IBM Business Process Manager Scripts such as Hijri and Hebrew, where the general flow of text proceeds horizontally from right to left, are called "bidirectional" scripts. The attribute "bidirectional" (bidi) is used for scripts, but by association, the languages that use bidirectional scripts are called bidirectional languages. Although bidi text runs in both directions, the right-to-left direction is the norm. - Contextual support IBM BPM offers contextual bidi support for languages such as Arabic and Hebrew, where the general flow of text proceeds horizontally from right to left. - Troubleshooting Process Designer and Process Center connectivity Resolve problems starting Process Designer, for example during login, by using various techniques such as correcting invalid connection information or logging errors that are captured with log4J or java.util.logging. - Enabling error logging in Process Designer You can configure IBM Process Designer to log errors by using log4J or java.util.logging. You can then examine the logs to troubleshoot problems with Process Designer. Parent topic:Building process applications

904

Bidirectional support in IBM Business Process Manager Scripts such as Hijri and Hebrew, where the general flow of text proceeds horizontally from right to left, are called "bidirectional" scripts. The attribute "bidirectional" (bidi) is used for scripts, but by association, the languages that use bidirectional scripts are called bidirectional languages. Although bidi text runs in both directions, the right-to-left direction is the norm. - If the direction of the window is right to left, its elements are logically ordered from right to left and from top to bottom. - Within a right-to-left window, the default direction of entry fields is right to left, but entry fields that are to receive English text or numeric input must be defined as having a left-to-right direction. - Within the same window, text and graphics can have different directions. IBM BPM provides built-in bidirectional (bidi) layout options for designing processes. Bidirectional support in IBM BPM includes the following features: - Contextual typing - Layout transformation in Process Designer - Islamic (Hijri) and Hebrew calendar support When you are creating user interfaces in IBM BPM, you can choose an Islamic or Hebrew calendar. If you are using heritage coaches to build your user interface, see Configuring a Hebrew or Islamic calendar. If you are using coach views, see Coaches toolkit: Date Time Picker stock control. - Applying bidirectional text layout transformation IBM BPM provides bidirectional (bidi) text layout options for process applications. Bidirectional text layout transformation can be applied to any string variable (either input or output) as part of the preprocessing, postprocessing, or implementation of a service. Typically, bidirectional text layout transformations are required for conversion of bidi textual data stored in databases to a Logical LTR format that is assumed by the BPM user interface, but can be used for other purposes. Parent topic:Globalization

905

Applying bidirectional text layout transformation IBM BPM provides bidirectional (bidi) text layout options for process applications. Bidirectional text layout transformation can be applied to any string variable (either input or output) as part of the preprocessing, postprocessing, or implementation of a service. Typically, bidirectional text layout transformations are required for conversion of bidi textual data stored in databases to a Logical LTR format that is assumed by the BPM user interface, but can be used for other purposes.

About this task Complete the following steps for bidi text layout transformation:

Procedure 1. From the palette, add a server script to a service, such as a heritage human service.Note: This transformation can be performed from any server-side service. To perform a text layout transformation in a client-side human service, include a call to a server-side service, such as an integration service, from within your client-side human service flow. 2. In the Variables tab for the service, add an input string variable for the string to be transformed. 3. In the Diagram tab, select the server script. 4. In the Implementation tab of the Properties view, enter the script for calling the bidi engine to implement the transform. For example:tw.local.Var = tw.system.bidiTransformation(tw.local.Var,"input_bidi_format", "outputBidiFormat", symmetricSwapping)

where tw.local.Var1 is the string to be transformed.The input BidiFormat and output BidiFormat can have the following values: - LLTR - logical left-to-right - LRTL - logical right-to-left - LCLR - logical contextual left-to-right - LCRL - logical contextual right-to-left - VLTR - visual left-to-right - VRTL - visual right-to-left - VCLR - visual contextual left-to-right - VCRL - visual contextual right-to-left In the following example, a logical left-to-right string is transformed to LRTL logical right-to-left and the Boolean value isSymmetricSwapping is set to true: tw.local.Var1 = tw.system.bidiTransformation(tw.local.Var1,"LLTR", "LRTL", true)

5.

What to do next To test your service, wire it to a coach that has an input variable and text control that is bound to the transformed string variable, then run the coach. Parent topic:Bidirectional support in IBM Business Process Manager

906

907

Contextual support IBM® BPM offers contextual bidi support for languages such as Arabic and Hebrew, where the general flow of text proceeds horizontally from right to left. Contextual support ensures that when a first typed character is Hebrew or Arabic, control orientation and typing direction are right-to-left, and that the text alignment is right. The following is a list of the different kinds of contextual support that IBM BPM provides. - Contextual support for names of diagram elements ensures correct display of bidi text not only in properties but also in diagram. - Contextual support in notes ensures right-to-left text direction of text inside the notes. - When a new activity is dragged from the palette and dropped onto the business process definition (BPD) canvas, contextual typing of the activity name is possible inside the BPD diagram. - Contextual typing is supported in descriptions in Process Center. Parent topic:Globalization

908

Troubleshooting Process Designer and Process Center connectivity Resolve problems starting Process Designer, for example during login, by using various techniques such as correcting invalid connection information or logging errors that are captured with log4J or java.util.logging. You might encounter an error message similar to this one when you start Process Designer:Unable to establish a connection with the Process Center When you start Process Designer, you must log in using your IBM® BPM user name and password. If you do not already have a user account, contact your IBM BPM administrator. When you log in, you are connected to the Process Center designated during installation of Process Designer. To determine your connection status, check the lower right corner of the Process Designer. This area of the Designer interface displays status conditions.Table 1. Indicator colors that describe status conditions on the Designer interface Indicator color Green Yellow Orange Red

Connection to Process Center Server status Good connection Slow connection that might cause issues with concurrent edits Even slower connection and more potential issues with concurrent editing No connection; check with your IBM Business Process Manager administrator to ensure the Process Center Server is up and running

If you see a connection error after you log in, try one of the following tasks: - Confirm that you are using the correct user name and password. - Confirm that Process Center is running by accessing it through a browser using the URL in the form http://hostname:port/ProcessCenter. The default port is 9080. - Check the eclipse.ini file (in the Process Designer installation directory) to confirm that the Process Center connection information is correct: 1. Find the installation folder of Process Designer on your local computer, for example C:\IBM\ProcessDesigner\v8.5. 2. Open the eclipse.ini file and locate -Dcom.ibm.bpm.processcenter.url. Ensure that the URL prefix (http://hostname:port) is the same as the Process Center URL prefix. - Confirm that your Process Designer version matches the Process Center version. If your administrator upgraded Process Center, you need to upgrade Process Designer to the same version by accessing Process Center from a browser and downloading Process Designer.If the two versions are different, you might see a message similar to the following message: The versions of Process Center("BPM8501-20130922-000036") and Process Designer ("BPM8500-20130525-092636") do not match.

909

- If you see a blank white Process Designer view or the view does not display fully, or if you see an HTTP error, press F5 to refresh. If the display continues to be blank, enable a security option as described in Process Designer window is blank. - Process Designer communicates with Process Center using the following ports. If you have a firewall or proxy server, or are running a service that forwards the ports, check that communication on the following ports is enabled.Table 2. Process Center ports accessed by Process Designer Port Name BOOTSTRAP_ADDRESS CSIV2_SSL_SERVERAUTH_LI STENER_ADDRESS ORB_LISTENER_ADDRESS SIB_ENDPOINT_ADDRESS SIB_ENDPOINT_SECURE_AD DRESS WC_defaulthost WC_defaulthost_secure

Default Number 2809 9403 9100 7276 7286 9080 9443

The default ports depend on the server type. Refer to Port number settings in the WebSphere Application Server information center. - Examine the IBM Business Process Manager logs for errors or information. See IBM Business Process Manager log files. - Turn on Log4J debug level tracing. See Enabling log4J debug tracing - Use java.util.logging to write errors to a log. See Enabling java.util.logging

- Enabling error logging in Process Designer You can configure IBM Process Designer to log errors by using log4J or java.util.logging. You can then examine the logs to troubleshoot problems with Process Designer. Parent topic:Globalization Parent topic:Building process applications

910

Enabling error logging in Process Designer You can configure IBM® Process Designer to log errors by using log4J or java.util.logging. You can then examine the logs to troubleshoot problems with Process Designer.

Traces and logs Error logs and traces can be located in a number of different places within the Process Designer installation directory. You can find ae.log in the main directory where Process Designer is installed. Other logs are located in the \workspace\metadata directory. You can use the information in these logs to troubleshoot a problem. If you need to contact IBM Support, submit these logs to get the problem resolved faster.

Enabling log4J debug tracing Configure Process Designer to add debug statements to the ae.log file: 1. Close IBM Process Designer. 2. Locate the file twappserver.jar in the directory \teamworks\eclipse\plugins\teamworks.appserver.websphere_version\lib

3. From twappserver.jar, extract the file log4j.xml to the root Process Designer installation directory. 4. In log4j.xml, change the level value for the com.lombardisoftware logger from error to debug. The log4j.xml file should be changed from:







to:



5. Open eclipse.ini and point to the updated log4j.xml by adding this line:Dlog4j.configuration=file:/log4j.xml

6. Restart Process Designer, recreate the problem, and note down the time stamp. The ae.log file should now contain the debug and error messages from Process Designer.

Enabling java.util.logging To enable logging for all java.util.logging messages, follow these steps: 1. Close Process Designer.

911

2. Navigate to the main Process Designer installation directory 3. Open eclipse.ini and add this line:-Djava.util.logging.Level=ALL 4. Restart Process Designer, recreate the problem and examine the logs for errors.

Parent topic:Globalization Parent topic:Troubleshooting Process Designer and Process Center connectivity

912

The context object The context object provides access to helper functions, such as a callback to fire a named boundary event.

Properties Through the context object, you can access its properties. Property context.binding

Description Provides access to the data object that is bound to the current view. To access the data, use the following call:this.context.binding.get("value") Where value is a special property name that returns the bound data object.For example, if a view is bound to local.phoneBook.title, the view can get the title by using the following code:if (!! this.context.binding){ var title = this.context.binding.get("value") }

context.contextRootMap

Contains the values of different context roots of the IBM® BPM servers. Use this API to construct the URL that your coach views use to connect to these servers. The object has the following properties:rest (String).IBM BPM REST server such as "/rest/bpm/wle"teamworks (String). IBM BPM Teamworks server such as "/teamworks"processPortal (String).IBM Process Portal server such as "/ProcessPortal"

context.element

context.options

Contains the root DOM element of the coach view. The view must not delete this DOM element. Views that are defined in the layout are children of this root element. Generally, the view uses this root DOM element to locate its own content.Note: Multiple instances of the same view can be on the same HTML page. Use this root DOM element to scope your search. Provides access to the configuration options of the view. These configuration options include the properties that users can set for the view such as the label for a button control and metadata properties.

913

context.subview[viewid]

context.bpm.system

Returns an object with the div ID of the subview as a property name. In a nonrepeating scenario, there is usually only one property. Generally context.getSubview() is a more convenient function to use.viewid (String). The view ID or control ID. For more information, see Example: Get and use a domNode and Example: Get a div ID. Provides access to the following system values:baseTextDirection (String) . The text direction preference of the user.caseFolderId(String). The ID of the case folder if the current human service is running in the context of a case instance; otherwise the returned value is an empty string.enablingDocumentId (String). The ID of the document that activated the case activity whose implementation the current human service belongs to. An empty string is returned if the triggering activity was not activated by a document or is not a case activity.instanceId (String). The instance ID of the BPD in which the coach is running.paId (String). The ID of the process or toolkit that contains the coach definition.paShortName (String). The acronym of the process or toolkit that contains the coach definition.snapshotId (String). The ID of the process or toolkit snapshot that contains the coach definition.startingDocumentId (String). The ID of the case starting document if the current human service is running in a case instance that was started by a document filed event; otherwise the returned value is an empty string.taskId (String). The ID of the current task or process in which the coach is running.user_id (String). The ID of the user.user_loginName (String). The name that the user used to log in.user_fullName (String). The full name of the user.user_localeCountry (String). The locale of the user.user_localeLanguage (String). The language of the user.

914

context.bpm.system.settings

Provides access to the following properties related to timer-based refreshing for coach views: TimerCoachViewEnabled (Boolean).

context.bpm.team.manager

context.bpm.team.member

context.viewid

This setting specifies the active or inactive status of the timer coach control used on the default instance details user interface to trigger automatic refreshes. By default, this setting is true, which means the timer control is active.TimerCoachViewRefreshInterva l (Integer). This setting specifies the frequency of refresh requests triggered by the timer coach control. The value is defined in seconds. The default value is1, indicating that the value used in the coach control configuration is to be used. Administrators can override the settings specified in the models using this property.MinimumCoachViewRefreshInt erval (Integer). This setting defines the minimum time between refresh requests handled by the instance user interface coach controls. The value is defined in seconds. The default value is 10, which means that refresh calls to the server are only sent if at least 10 seconds have passed since the last refresh call. Lists the teams that the current user is manager of. The list ("[]") is empty by default. Each item in the list for context.bpm.team.manager is an object that contains the following properties: name (String). The name of the teamid (String). The unique identifier of the team. Lists the teams that the current user is member of. The list ("[]") is empty by default. Each item in the list for context.bpm.team.member is an object that contains the following properties: name (String). The name of the teamid (String). The unique identifier of the team. Contains the unique identifier for this view definition. Multiple view instances might have the same viewId. For more information, see context.getSubview(viewId, requiredOrder).

915

Functions Through the context object, you can access its functions. Function context.bindingType() context.broadcastMessage(message)

context.cancelBoundaryEvents()

context.containDiffLoopingContext()

Description Returns the type of the data binding. Broadcasts the supplied message.Important: Do not use this API to send sensitive or confidential information. message(Object). An object that has a name property. Cancels the boundary events that have not been sent to server. If a callback function was supplied when the boundary event was triggered, the coach framework calls the callback function to update the status of the boundary event. For more information, see the context.trigger(callback) function. Returns a value of true if the following conditions are true:A coach view that is bound to a list contains a content box that contains a coach view.This contained coach view is bound to the currentItem of a different list.For example, the API returns a value of true for the following structure:TableView (bind to ListA[]) ContentBox TextView (bind to ListB.currentItem)

The framework displays a message at run time when there is a mismatch in list lengths. For example, the message occurs for the previous example if ListA has four items and ListB has three items. For more information, see Data binding for coach views. You use containDiffLoopingContext() to, for example, determine whether to disable the add-and-delete capability of a table during the runtime even if a user specifies to enable the add-and-delete capability. Important: If the coach view that contains a view-managed content box is bound to a list that is not empty, do not call this API between deleting a domNode of the content box and the rendering of the first repeating element. The return value might not be accurate.

916

context.createView(domNode, index, parentView)

Creates a coach view instance and any subview instances under the specified DOM element, which is usually a content box div. domNode(Element). The HTML DOM element of the content box or node of any coach view.index(Integer) (optional). Indicates the position so that data binding and configuration indexes can be adjusted or zero-indexed. parentView(CoachView) (optional). The view instance of the parent view; alternatively, the parent view can be computed based on the document order. If domNode is the node of any view other than a content box, the framework creates a single instance of the view and returns it. If (domNode is the node of a context box, the framework creates view instances for all the views that are owned by the content box. The framework recursively creates views for all the framework-managed content boxes that are owned by the content box that is specified by the domNode parameter. The framework then returns an array of these view instances. The following code snippet shows how to create a content box view.var location = 5; var trElement = document.createElement("tr"); // rowTemplate is the contentBox that contains some nodes // the view nodes define table columns. var oneDiv = this.rowTemplate.cloneNode(true); trElement.appendChild(oneDiv); this.tableElement.appendChild(trElement); var viewArray = this.context.createView(oneDiv, location);

context.deleteView(domNode)

For more information, see Example: Get and use a domNode. Deletes the coach view instance and any subview instances, starting from the specified DOM element.domNode(Element). The HTML DOM element of content box or the node of any coach view.The following code snippet shows how to delete a view instance:var nodeToDelete = document.getElementById("myId"); this.context.deleteView(nodeToDelete); nodeToDelete.parentNode.removeChild(nodeToDelete);

For more information, see Example: Get and use a domNode.

917

context.getDomNode(uniqueViewId, optParam)

context.getInheritedVisibility()

context.getOptions(viewDomNode)

Returns the first match of the DOM node that has its data-ibmbpm_uniqueViewId property that has the specified ID or null if there is no match. The search starts with the parent DOM node of the this.context.element unless you pass in a different start node by using optParam.startNode and the search checks only the immediate children of the start node unless you pass in optParam.deepSearch=true.uniqueViewI D(String). The value to search for in the data-ibmbpm_uniqueViewId of the domNode.optParam(Object) (optional). Parameters that modify the scope of the search. Returns a String containing the value of the visibility setting of the ancestors of the coach view that is calling this function. If visibility values of all of its ancestors are set to DEFAULT, the function returns EDITABLE. Returns the options object for the coach view given its viewDomNode. The options are returned even when the view represented by viewDomNode is not yet constructed. Typically, use this API in a view to look at the configuration options (such as label or visibility ) of one of its child views before it is created. viewDomNode(Element). The HTML DOM element of the child view.The following code snippet is an example of how you could use this API: var childOptions = this.context.getOptions(childViewDomNode); var childLabel = childOptions._metadata.label.get("value"); childOptions._metadata.visibility.set("value", "READONLY");

context.getStyle()

Returns the currently applied positioning information specified in the Positioning properties of the coach designer. The currently applied positioning is based on an inheritance model where settings for larger screen width are applied to smaller screen sizes if nothing is specified for the smaller screen sizes. If a given property is not specified for any screen size, null is returned. The following properties are defined: width(String) height (String) min-width (String)minheight (String)margin (String)padding (String)overflow (String)

918

context.bind(type, callbackFunc, scopeObject)

context.setGroupNotification()

Registers a callback function to receive a change notification associated with the specified type. For now, only thestyle type is supported. Any other values will cause an exception to be thrown. This setting change can be a design-time change in the positioning settings or a change in the run-time screen size.Normally, the callback function invokes the context.getStyle() method to get the currently applied positioning. Only one notification or callback is triggered even if more than one positioning property is changed. This function returns an object that can be used to unregister the callback. The returned object contains a unbind() method that takes no parameter. type(String). Currently, the only supported value is style. callbackFunc(Function). The function to be invoked as a callback. This function has no type parameter.scopeObject(Object) . (Optional) Indicates the "this" to be used when invoking the callback function. If it is not specified then no scope is defined. When enabled, allows a coach view to receive notification of data binding and configuration option changes in a single notification for all changes within the current thread. The event object that is passed into the callback contains a single property type of value groupNotification. It does not have any information about the individual changes. Coach views should retrieve the latest binding and configuration option values after receiving the group notification. The following parameters are defined: enable(boolean). A value of true enables the group notification. A value of false disables the group notification. callback (function). Specifies the callback to call when group notification is enabled. When enable is set to set to false, all previous callbacks will be removed. scope(Object) The function scope when the callback is invoked.

919

context.getSubview(viewId, requiredOrder)

Returns the subview instance given the subview ID. This method is similar to context.subview[viewid] except that the return value is an array of subview instances. viewId(String). The view ID or control ID of the subviewrequiredOrder(boolean) (optional). Indicates whether the array that is returned must maintain the same order as in the DOM tree. The default value is false. The call this.context.getSubview("viewid")

returns an unsorted array of subview objects. The call this.context.getSubview("viewid", false) returns the same array. The only

difference between the two calls and the function call this.context.getSubview("viewid", true) is that this.context.getSubview("viewid", true) returns an array of subview

context.htmlEscape(text)

context.isTrustedSite(origin)

objects whose order matches the order of the DOM nodes in the DOM tree. For more information, see Accessing a child coach view by using a control ID. Escapes the specified text. This function is used to avoid potential cross-site scripting (XSS) attacks. text(String). The text to escape. The escaped text is returned. Returns true if origin matches the protocol, host, and port of the coach or a site listed on the white list. For example, a coach view receives a postMessage event. The coach view can check the origin of the event by calling this API using event.origin as the parameter.origin(String). The protocol and host of the URL. The origin must also include the port if the URL does not use the default port for the protocol. Examples of origin include https://bpm1.mycompany.com:9080, https://bpm2.mycompany.com:9443, and http://bpm3.mycompany.com.

920

Returns the parent view instance or null if there is no parent view. During the invocation of load(), the parentview object is created but not fully initialized. One reason it is not initialized is that load() of the parent view is called after the current load() function. Because the parentview object is not fully initialized, avoid calling this function in the load() function. context.refreshView() Forces the coach view and all its subviews to rebind. As a result, the change() callback is called, which causes the view (and all its subviews) to refresh. context.setDisplay(isDisplay, Shows or hides the specified DOM domNode) element by removing or adding a CSS class that sets display:none. When the domNode is hidden, the parent coach or coach view does not reserve the space that domNode would occupy. isDisplay(Boolean). The value true shows the domNode; the value false hides the domNodedomNode(DOMElement) (optional). If not specified, the root element of the current view is used. For more information, see Example: Get and use a domNode. context.setUniqueViewId(uniqueViewId Sets the uniqueViewId in the data, targetNode) ibmbpm_uniqueViewId property of the targetNode. If the call does not include the targetNode, this function sets the property for the DOM node of the this.context.element.uniqueViewId( String). The ID to be set.targetNode(Element) (optional). The HTML DOM element that contains the data-ibmbpm_uniqueViewId property to be set. context.setVisibility(isVisible, Shows or hides the specified DOM domNode) element by removing or adding a CSS class that sets display:hidden. When the domNode is hidden, the parent coach or coach view reserves the space that domNode would occupy. isVisible(Boolean). The value true shows the domNode; the value false hides the domNodedomNode(Element) (optional). If not specified, the root HTML DOM element of the current view is used. context.parentView()

921

context.subscribeValidation()

context.trigger(callback options)

Registers the coach view to receive the validation errors of descendant views that are bound to a different business object than the current view. These errors are contained in the errors_subscription list of the error event object. Views that do not have a data binding, such as the Tab stock control, can use this API to receive validation errors. Fires a named boundary event. callback(function) (optional)If a callback function is supplied, the coach framework calls the callback function when the boundary event is handled depending on the supplied options parameter. The callback function has a response object as a single parameter: {status: boundaryEventStatus}. The boundaryEventStatus parameter has one of the following values: options(Object) (optional)This

parameter has a single property: callBackForAll (Boolean). If any of the following conditions apply, the callback is only invoked when the boundary event was successfully run (executed):The options parameter does not exist.The options parameter exists but does not contain the callBackForAll property. The options parameter exists and it contains the callBackForAll property but the property is set to false. If the property is set to true, the callback is invoked regardless of the status of the boundary event. context.triggerCollaboration(payload Fires a custom collaboration event. The ) custom message is sent to the browser of a collaborating user. The corresponding view on the collaborating browser receives the collaboration() callback with event.type = "custom". payload(Object). The object that contains the custom message contents. context.unsubscribeValidation() Unregisters the Coach View so that it no longer receives errors in the errors_subscription list. The view still receives the errors list if it exists.

Example: Get and use a domNode 922

Many functions of the context object take a document node (domNode) as an argument. The following code example shows how to get a domNode and use it in a function. 1

var subview = this.context.getSubview("subviewID", "true")[5];

2

var subviewDomNode = subview.context.element;

3

this.context.deleteView(subviewDomNode);

- 1 The parameter subviewID is the control ID of the subview and corresponds to the value for the property data-viewid of the