ContentsBuilding 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 9 . you must understand the tools that are available in the Process Designer interface. Note: Users who have administrative access to the application control access to process applications. The Process Designer interface provides the tools to model your processes in IBM BPM. as described in Managing library items in the Designer view. Table 1. For more information. Provides access to the library items for the current process application. take a snapshot. see Managing access to the Process Center repository. 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. Also provides access to Process Center and Optimizer if you open the Process Designer desktop editor. You can create and edit library items.Process Designer interface Before you start to build processes with IBM® Process Designer. The main toolbar is also where you go to save all open editors. and view web-based help. 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. Where you can set properties and configuration options for selected components in your process.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. and heritage human services. . Provides BPMN elements and variables that you can use to model and configure your process. human services. Table 1. they open in the desktop editor so that you can edit them.Open Process Designer desktop editor. The following table lists which artifacts you can edit where (indicated with asterisks). 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.Open Process Designer desktop editor and then select an artifact that is editable only on the web. For example. and then right-click and select Open in > Web Editor. to create process applications that contain business process definitions (BPDs) and client-side human services. Now. Editable in the Process Designer web editor * * 11 . You can access the Process Designer web editor in the following ways: . Multiple users can work simultaneously on the same process applications and artifacts in the two editors and changes happen automatically and seamlessly. When you click the artifacts in the web editor. or document type. If you have Process Designer open on your desktop and you are working in the web editor. case type. select a coach view. you can work with artifacts that are in the Process Designer web editor and in the Process Designer desktop editor. You can edit some artifacts in the desktop editor. . you worked with artifacts in Process Designer on your desktop. such as a client-side human service. You can edit other artifacts in the web editor. 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. you can edit certain artifacts in the desktop editor. Case management functions are only available if you have IBM BPM Advanced with the Basic Case Management feature installed. The web editor opens in a web browser from Process Designer.Where to edit Process Designer artifacts Learn where you can edit artifacts in IBM® Process Designer. In previous releases. you need to edit this artifact in the Process Designer desktop editor. you must edit coach views in the web editor.coach viewNote: To use responsive features in coach views. 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. timing interval tracking group undercover agent user attribute definition web file * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * 12 . for example to have the runtime behavior respond to different screen size environments. 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. web service * Parent topic:Getting started with IBM Process Designer 13 . You can see updates that are made by other users as described in Concurrent editing. . see Managing external files. When you start using the Designer interface in Process Designer. you can hide the library by clicking the toggle at the bottom of the Revision History. . .To maximize the space available for in the main canvas. changing. 14 .To group library items for easy access. . . follow the instructions in Organizing library items in smart folders. press Ctrl+Shift+O. Click the toggle icon and the palette margin to restore the library and the palette. click the arrow keys or the menu at the top of the window.To add and manage external files as part of your IBM® BPM project. . press Ctrl+Shift+N. .To choose multiple items in a category.Click the "Hide the Library" icon at the top left corner of Process Designer to hide the library.To open an existing library item while you are working in the Designer view. you can create favorites as described in Creating favorites. . .For quick and easy access of particular library items.You can revert to a previous snapshot (version) of a library item as described in Reverting to a previous version of a library item. The following are tips and shortcuts for the Process Designer web editor: .To move or copy library items from one process application to another. press and hold the Ctrl key and then click each item. You can also hide the palette by clicking the left margin of the palette.You can add a dependency to a toolkit to use the library items from that toolkit as described in Creating. .To create smart folders of library items. . . follow the instructions in Tagging library items. follow the instructions in Copying or moving library items. .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 resize the palette and the main canvas and you can also hide the property manager by clicking the arrow below the main canvas. The following are tips and shortcuts for the Process Designer desktop editor: .To create a new library item while you are working in the Designer view.Unsaved changes have an asterisk next to the item name at the top of the window. there are some tips and shortcuts to keep in mind.To move from one open library item to another. and deleting a toolkit dependency in the Designer view.You can capture your development progress in snapshots as described in Creating snapshots in the Designer view. .Process Designer tips and shortcuts You can use several features in Process Designer to improve your efficiency.To maximize the space available for the main canvas. . . . . Parent topic:Getting started with IBM Process Designer 15 . . . follow the instructions in Copying or moving library items. . press and hold the Ctrl key and then click each item.You can see updates that are made by other users as described in Concurrent editing.To tag library items for easy access. .To move or copy library items from one process application to another.To move from one open library item to another.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.To choose multiple items in a category.To add and manage external files as part of your IBM BPM project. . click the arrow keys or the menu at the top of the window. follow the instructions in Tagging library items. changing.You can capture your development progress in snapshots as described in Creating snapshots in the Designer view. .. see Managing external files. and deleting a toolkit dependency in the Designer view. When another user opens a library item by showing a user icon. . you collaborate with other team members to create the library items that you need for your project. ensure that your connection status is good. as shown in the following screen capture: You can also see when others are viewing or editing the same library item. When you edit concurrently with other users. by displaying a warning icon and message to suggest to each user that they either immediately save their changes or discard them. as shown in the following screen capture: When multiple users work on the same library item. .When another user has saved changes while you are editing a library item by displaying the words Read Only next to the library item. 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. 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. To ensure that all users are aware which library items are open and what changes are being made. you can see when other users are working in the same process application. . When you are working in the Designer view. Process Designer provides the following notifications: .When another user is editing a library item by displaying the words Read Only next to the library item.When multiple users start to edit a library item at the same time. such as a human service. For example. the library item will be available to edit. before the Read Only text appears. each user can see the changes when edits are saved.Concurrent editing Multiple users can simultaneously access and change process applications and library items in IBM® Process Designer. When you edit concurrently. When a user saves their work. Parent topic:Getting started with IBM Process Designer 16 . You can hover over the icon to see who that user is. you can communicate about your ideas and edits with instant messaging and see the results in the Designer view as they happen. When you click Save. Select File > Preferences from the main menu. change the Optimizer to the following preference setting: Use the KPI threshold values from the actual version of the Process App/Toolkit. you must enable IBM BPM Developer Capability and IBM BPM Advanced Features. 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. For example. 3. Click the IBM BPM entry to display the available options. Process Designer preferences The following steps describe how to access the preference settings and the following table describes the options that are available: 1. Table 1. you can choose whether to display JavaScript warnings. For example. 17 . to set the user name for Blueworks Live™ process subscriptions. click the Blueworks Live option. Set options for the Optimizer.Tip: Changing the email address or the URL logs you out of Blueworks Live. Control the locale setting for BAL Rules.Setting preferences IBM® Process Designer provides several settings to control the appearance and functionality of the editors and interfaces that it includes. For example. 2. Click the option that you want. 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. the KPI thresholds that are used by the Visualization Modes are the thresholds from the current working version of your process application or toolkit. Set preferences for the JavaScript editor included in IBM Process Designer. to create external activities in IBM Process Designer. For example. Control the capabilities of the current user. ) The locale preference that you selected applies to the user who logs in.Passwords Web Browser Manage the passwords that are stored when running tasks from the Inspector. access the Process Center Console by opening your web browser to the following location: http://[host_name]:[port]/ProcessCenter. . These properties affect the connections created between Process Designer and Process Center. Based on your business requirements. which configures the URLs that are used in the Process Designer authoring environment to get images. 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. see the following table that contains properties and explains how to set the properties. (When you are accessing Process Center Console from a browser. When you change the locale. If you do not see a particular external web browser as an option. The AuthoringEnvironmentConfig object contains the following properties: Name Images Prefix Description The Images Prefix endpoint maps to the AE_IMAGES_PREFIX scenario key. you must exit and then restart IBM Process Designer for the change to take effect. For IBM BPM XML configuration settings that are related to Process Designer. 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. you might want to change the properties of Process Designer. Each IBM Business Process Manager interface that is started by the same user in the same environment uses this preference setting. Process Center Console preferences To set the locale for IBM Process Center Console and Process Designer. click New to add it. Click Preferences in the upper right corner and choose the language that you want from the list. you can log out and then log back in for the change to take effect. Select the web browser to use when web pages are opened from IBM Process Designer. which configures the URLs that are used in the Process Designer authoring environment to reach the repository. which configures the URLs that are used in the Process Designer authoring environment to reach the web API. 19 . Repository Prefix The Repository Prefix endpoint maps to the AE_REPOSITORY_PREFI X scenario key. 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 authoring environment to reach Process Portal. which configures the URLs that are used in the Process Designer. Web API Prefix The Web API Prefix endpoint maps to the AE_WEBAPI_PREFIX scenario key.Portal Prefix The Portal Prefix endpoint maps to the AE_PORTAL_PREFIX scenario key. 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. 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. 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. which configures the URL that is used in the Process Designer authoring environment to reach the Process Center REST Gateway. For information about setting the context root prefix. The context root of the URL can be customized by adding a prefix before the context root.war file. Web PD Prefix The Web PD Prefix endpoint maps to the AE_WEB_PD_PREFIX scenario key.The host and port number of the URL can be customized by setting the IBM BPM virtual host. . which configures the URL that is used in the Process Designer authoring environment to launch the web editor. see the topic BPMConfig command-line utility. 20 Information on setting the IBM BPM virtual host is found in the topic Configuring endpoints to match your topology.REST Gateway Prefix The REST Gateway Prefix endpoint maps to the AE_REST_GATEWAY_CR _PREFIX scenario key. but not exclusively. 21 Information on setting the httpProtocolOnly attribute is found in the topic Configuring the httpProtocolOnly property for Process Designer.war file. The host and port number of the URL can be customized by setting the IBM BPM virtual host. Note that if the attribute is not set.Process Portal Prefix HTTP Protocol Only The Process Portal Prefix specifies the endpoint of the web application contained in the processportal. . /prefix/ProcessPortal. communication between Process Designer and Process Center is limited to using HTTP or HTTPS protocols instead of RMI with JMS. If this attribute is set (which is the default). For example. The context root of the URL can be customized by adding a prefix before the context root. HTTP or HTTPS communication still occurs between some Process Designer components and Process Center. For information about setting the properties.###. 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.## €"/> <formatting-template comment="Currency" template="€ ###.Suppress Redirect URL Password Specifies whether to suppress the inclusion of the user password in the URLs that Process Designer opens.###"/> <formatting-template comment="Decimal" template="###. which consist of the user ID and password. each time you run a playback in Process Designer.###. suppressRedirectUrlPas swd option stops the password from being included in the URL to improve security.###.###. Specifies the predefined character formats for text controls or specifies the creation of additional formats.###.###. Process Designer then submits the user credentials.xml. The Information on setting the suppressRedirectUrlPas swd attribute is found in the topic Installing IBM Process Designer.###. This option only applies to Process Designer and can be turned on and off as needed. see the topic Changing IBM Process Server properties in 100Custom. a new Process Portal browser session is opened.##"/> <formatting-template comment="Integer" template="###.###. Note: When you use the suppressRedirectUrlPas swd option. and the browser session uses these credentials to log in. .<authoring-environment merge="mergeChildren"> <formatting-templates merge="replace"> <formatting-template comment="Currency" template="$ ###.###. The data type is FormattingTemplatesConfi g.##"/> <formatting-template comment="US phone" template="(###) 0000000"/> <formatting-template comment="US SSN" template="000-000000"/> </formatting-templates> </authoring-environment> 22 These properties are all configured using IBM BPM configuration XML files.##"/> <formatting-template comment="Currency" template="###. For example. <authoring- environment merge="mergeChildren"> <mime-types merge="replace"> <mime-type type="application/javascript"/> <mime-type type="application/octetstream"/> <mime-type type="application/pdf"/> <mime-type type="application/xml"/> <mime-type type="application/xmldtd"/> <mime-type type="application/zip"/> <mime-type type="image/gif"/> <mime-type type="image/jpeg"/> <mime-type type="image/png"/> <mime-type type="text/calendar"/> <mime-type type="text/css"/> <mime-type type="text/csv"/> <mime-type type="text/html"/> <mime-type type="text/rtf"/> </mime-types> </authoring-environment> Repository Broken Ping Time Specify an integer value.<authoring-environment merge="mergeChildren"> <repository-max-wait-during-shutdown merge="replace"> </repository-max-wait-during-shutdown> </authoring-environment> 23 . The default value is 15000 if the value is set to 0 or a value is not specified.Inspector This property specifies inspector configuration.<authoring-environment merge="mergeChildren"> <sequenced-state-delta-manager> <fallback-timeout>15 </fallback-timeout> <slow-timeout>15 </slow-timeout> <scheduled-timeout-padding>15 </scheduled-timeout-padding> <time-in-fallback-before-link-reset>15 </time-in-fallback-before-link-reset> <time-in-fallback-after-link-resetbefore-full-reset>15 </time-in-fallback-after-link-resetbefore-full-reset> </sequenced-state-delta-manager> </authoring-environment> Mime Types The data type is MimeTypesConfig. The default value is 3000 if the value is set to 0 or a value is not specified. The data type is InspectorConfig.<authoringenvironment merge="mergeChildren"> <inspector> <target-servers> <type></type> <name></name> <default-action-policy> <action> <type></type> <role>role1</role> <role>role2</role> </action> </default-action-policy> </target-servers> </inspector> </authoring-environment> Library Event Stream Manager The data type is SequencedStateDeltaMan agerConfig.<authoring-environment merge="mergeChildren"> <repository-broken-ping-time merge="replace"> </repository-broken-ping-time> </authoring-environment> Repository Max Wait During Shutdown Specify an integer value. if you have a mix of secure and non-secure servers.<authoringenvironment merge="mergeChildren"> <deploy-snapshot-using-https merge="replace">true </deploy-snapshot-using-https> </authoring-environment> 24 . then communication from Process Center to Process Server will work with HTTP Secure (HTTPS) or HTTP over SSL. For example. However. a service can be started directly from IBM Process Designer without presenting a login screen.<authoring-environment merge="mergeChildren"> <repository-ping-delay merge="replace"> </repository-ping-delay> </authoring-environment> Repository Slow Ping Time Specify an integer value.Repository Ping Delay Specify an integer value. Process Center can only communicate with Process Servers that are configured to work with this mixed configuration. The default value is true.<authoring-environment merge="mergeChildren"> <add-redirect-url-credentials merge="replace">true </add-redirect-url-credentials> </authoring-environment> Deploy Snapshot Using HTTPS Specifies whether the Process Center Server uses HTTPS to deploy process applications and toolkits to process servers. The default value is 7500 if the value is set to 0 or a value is not specified. If the property is set to the default value of true and all process servers are secure.<authoring-environment merge="mergeChildren"> <repository-slow-ping-time merge="replace"> </repository-slow-ping-time> </authoring-environment> Add Redirect URL Credentials Specifies whether the credentials are permitted to be passed in IBM Business Process Manager URLs. The default value is 15000 if the value is set to 0 or a value is not specified. this property is set to true.Encode Redirect URL Credentials Specifies whether the credentials that are passed in an IBM Business Process Manager URL that implements redirectlogin. If you change the setting to false. For example.<authoring-environment merge="mergeChildren"> <encode-redirect-url-credentials merge="replace">true </encode-redirect-url-credentials> </authoring-environment> Parent topic:Getting started with IBM Process Designer 25 . which specifies that the credentials passed in an IBM BPM URL are encoded. you can encode credentials in a URL that is used to start a service directly from IBM Process Designer. By default. the URL is composed with credentials in plain text.jsp are encoded. 3. when you manipulate the items within the process application with the IBM BPM JavaScript API. In the Create New Process App window. . To create library items in the process application. you can select Allow users to open the process application in the web-based Case Designer. Tip: If you are creating processes in your process application. For more information. you can use the acronym to specify the namespace of the items. when you manipulate the items in the process application with the IBM BPM JavaScript API. 2. Ensure that the acronym for the process application is unique and limited to seven characters. when you manipulate the items in the process application with the IBM BPM JavaScript API. When you enter a description.Note:Case management functions are only available if you have IBM BPM Advanced with the Basic Case Management feature installed. you provide a name. you can view it in the Process Center console by clicking the question mark next to the process application name. In the Process Apps tab. enter a name. 4. If you are building cases in the process application. you can use the acronym to specify the namespace of the items. Providing a description is optional. click the appropriate option: . use the remote Process Center URL.Creating new process applications When you create a new process application. and description of the process application. The acronym for the process application must be unique and limited to 7 characters.Open in Designer Open in Case DesignerNote:Case management functions are only available if you have IBM BPM Advanced with the Basic Case 26 . IBM BPM uses the acronym as an identifier for this process application and the library items that it contains. see Opening Case Designer from Process Center. acronym. complete the following steps: 1. Start the Process Designer desktop editor or enter the remote Process Center URL into a web browser. and optional description of the process application. acronym. If you are building cases in your process application. click the Create New Process App option. use the Process Designer desktop editor. You can access the Process Center console in the following ways: . For example.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. Procedure To create a new process application. you can use the acronym to specify the namespace of the items. For example. For example. 5. About this task You create new process applications in Process Center. IBM® Business Process Manager (BPM) uses the acronym as an identifier for this process application and the library items that it contains. enable the tracks in the Process Center console. What to do next .To use tracks in this process application. Parent topic:Building process applications 27 .You can create toolkits to enable Process Designer users to share library items across process applications.Management feature installed. . You see the Open in Case Designer option only if you selected the option described in step 4. 0 archive (.zip) files. 28 . if necessary. Either of these actions will result in an import window. in the future. Start the IBM Process Designer from your Windows desktop or using the URL for the Process Center in a browser. 3. Note: Advanced integration services are only available for unimplemented services. The first time you start the IBM Process Designer it opens to the Process Center console. for your use as a baseline. 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. If you are using IBM BPM Advanced. You can import your models into the IBM Process Center. You can either click Import Process App (on the Process App tab). Integration services are always generated for implemented services.0 file archive (. About this task You can do this by importing the BPMN models that you exported earlier from WebSphere Business Modeler BPMN 2. you will see radio buttons that you can use to choose what will be generated for unimplemented services. A snapshot of the process application is automatically created in the Process Center.zip) file that you exported from IBM WebSphere® Business Modeler and click Next. see Building an Integration service and Building an Advanced Integration service. if you want to see the details of what was imported or to make changes to the imported models. containing the content from the BPMN 2. The Import Process App window displays. A Summary of the import results pane opens containing any generated error. It will include integration services if the model contained web service bindings and advanced integration services if the model contained unimplemented advanced integration services.Creating a process application from a WebSphere Business Modeler process You can import business processes from WebSphere Business Modeler to Process Designer. You can edit the name and acronym and add a description. You can then use the IBM Process Designer to open the resulting Process App or Toolkit.0 archive. 2. Both radio buttons display only in IBM BPM Advanced. A new process application or a toolkit is created. In the Import Process App window. Procedure To import BPMN models into the IBM® Process Center complete the following steps: 1. Click Browse to select the BPMN 2. 4. warning and information messages. a name and acronym have been specified based on information in the file you selected. or Import Toolkit (on the Toolkit tab). For more information. Click Import Process App.You can trigger the import of the models in two ways. Select either Advanced Integration Services or Integration Services and then click Next. B. Adjust the process layout to minimize connection crossing. Click Close.5. Open every single generated artifact and ensure that its contents appear as expected. All the messages will be saved as a text file even if a filter has been applied. 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. 29 . Javascript Activities: Enter the javascript logic D. Complete the following steps for each of the following artifact:Services: Enter the service flow details A. For each warning. Check for validation messages and fix them as necessary. 4. Human services: Customize the default generated coach B. 5. examine the contents of what was generated and take additional action as required. Replace any of the default generated logic with the intended logic wherever necessary. 3. 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. Open the Process App or Toolkit that you created 2. Rule services: Enter the rule details Teams: Specify the team members Processes: A. Parent topic:Building process applications Next Steps after importing BPMN Models Procedure 1. XOR and IOR Gateways: Enter the conditional logic C. Private Variables: Provide default values for any variables that are not initialized. Click Save and specify a location if you want to save the messages. Warnings usually indicate an unsupported construct or invalid input model. You can filter the messages by clicking Errors or Warnings. .Designing process interactions for business users After you deploy a business process definition that you have built in Process Designer to the Process Portal. . To take advantage of this information. you can analyze and simulate them in order to optimize your business activity. Parent topic:Building process applications 30 . you enable to design your processes to make them trackable. The following diagram illustrates the main tasks and activities that are associated with creating processes.Creating processes in IBM Process Designer Create processes in Process Designer that represent the processes in your company.Enabling processes for tracking and reporting IBM Business Process Manager provides ways to collect and consume process performance information.Modeling processes A process is the major unit of logic in IBM Business Process Manager (BPM). The user might be the one to launch the process. a business user might interact with it in a number of ways. It is the container for all components of a business process definition (BPD). When you run your processes inside Process Designer. or the user might be assigned individual activities in the process. . Modeling a good process that matches your requirements is at the core of Process Designer. 31 . an exception. . A BPD is a reusable model of a process that defines the common aspects of all runtime instances of that process model. 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. Each artifact in IBM Process Designer has a documentation field for this purpose. you must create a business process definition (BPD). And. update. You can manage inbound and outbound communication with external systems using undercover agents. Parent topic:Creating processes in IBM Process Designer 32 . or a incoming message from an external system. and integration services. It is the container for all components of a business process definition (BPD). Many different individuals from various organizations are involved in developing processes with IBM BPM. you might want to capture information about the artifacts that you are creating. manage errors.Modeling events Events in IBM Business Process Manager can be triggered by a due date passing. . . Java and databases You can configure IBM BPM processes to communicate with an external system to retrieve.Modeling processes A process is the major unit of logic in IBM® Business Process Manager (BPM).Integrating BPDs with IBM Case Manager cases To integrate with IBM Case Manager. . and retrieve information about the execution of your BPDs.NET application. during. web services.Documenting development artifacts As you develop your process application. When a BPD starts and the tasks within it are invoked. Modeling a good process that matches your requirements is at the core of Process Designer. 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. as specified in the IBM Business Process Manager overview. services perform the required functions. Use events to track data.Creating a business process definition (BPD) To model a process. or insert data. team members must work together to capture process requirements and iteratively develop the model and its implementations. . or at the end of a process.Building services Use services to implement the activities in a business process definition (BPD). . you can model an activity that is run by a custom Eclipse RCP or Microsoft . 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. external applications can call into IBM BPM to initiate services. For example.Integrating with web services. You can add events to your BPDs that can occur at the beginning. . 33 . Each lane that you create is assigned to the All Users group by default. However. not in a toolkit. and the sequence of the workflow between the activities. which is a special security group that automatically includes all users in the system. During implementation. A BPD in a toolkit can result in process instances running inside the toolkit. The trigger that you want determines the type of event you choose to implement. About this task Process modeling captures the ordered sequence of activities within a process along with supporting information from end to end. you can create a BPD that groups the activities of a group and a system into a single lane if that is your preference.Tip: When you create a BPD. The All Users group includes all users who are members of the tw_allusers security group. the business process is framed in a BPD to reflect the activities. A lane can be a participant lane or a system lane. You can designate any specific person or group to be responsible for the activities in a participant lane.Creating a business process definition (BPD) To model a process. Events in IBM BPM can be triggered by a due date passing. Procedure 34 . an exception. In process modeling. 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. conditional branching. you need to declare variables to capture the business data that is passed from activity to activity in your process. the roles that conduct those activities. You can also add events to a BPD. A system lane contains activities handled by a specific IBM Process Center system. A process instance running in a toolkit cannot be migrated. Each activity needs an implementation. For each BPD that you create. A business process definition needs to include a lane for each system or group of users who participates in a process. or a message arriving. a developer creates a service or writes the JavaScript necessary to complete the activities in a system lane. A BPD is a reusable model of a process that defines the common aspects of all runtime instances of that process model. you must be in the IBM® Process Designer desktop editor. Ensure that you have access to a process application in the Process Center repository. Before you begin To perform this task. Tip: Create BPDs in a process application. you must create a business process definition (BPD). You can use this default group for running and testing your BPD in the Inspector. which defines the activity and sets the properties for the task. BPMN also compacts your BPD by using symbols to represent ideas. select the element in the diagram and edit its properties in the Properties view. or you can assign teams for individual activities and lanes. determining branching and merging of the paths that a runtime process or case instance can take.Assigning teams to BPDs and lanes Assign teams of users that can start activities. 2. during. .Implementing activities in a BPD Choose the implementation for each activity in your BPD and set the required properties. Open the Process Designer desktop editor.Adding activities to a BPD In a business process definition (BPD). based on scripted rules. and teams that can work on activities in Process Portal.Adding events to a BPD When modeling a process.Example gateways The following samples illustrate how to model several types of gateways. you might want to model events that can occur at the beginning. . . . 5.Modeling process execution paths by using sequence flows Use sequence flows to connect activities and other modeling constructs to establish the process flow. Design your process by dragging BPMN elements from the palette onto the diagram area.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.1. .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. . you can designate the users who receive the runtime task by using the Assignments page in the properties for that activity. . Open a process application in the Designer view. A lane is the container for all the activities to be carried out by a specific team or by a system. The decision to skip or complete a conditional activity can be made by the runtime user or programmatically. . . you can include activities that represent logical work that a specific team or a system completes. 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.Assigning teams to BPD activities For any activity with a service implementation. 3.Creating an unstructured (ad hoc) activity An ad hoc activity has no input wires and is started as required by knowledge 35 . or at the end of a runtime process (as opposed to activities that are carried out by participants in the process). To specify the details for an element. You can assign a team of instance owners for a BPD. 4. . .Converging and diverging flows Gateways control the divergence and convergence of a sequence flow. . Steps in a subprocess can directly access business objects (variables) from the parent process.Creating user interfaces for a BPD Create customized user interfaces that a user sees for the process instance in Process Portal. a subprocess can be accessed and instantiated only from the parent BPD. No data mapping is required. However. unlike a linked process. . .Task types Learn more about the task types that are available when modeling with IBM Process Designer. Such activities can be required or optional.Validating processes Use validation functions to refine process definitions as you build them.Subprocess types Subprocess is an option for encapsulating logically related steps within a parent process. rather than by a predefined process flow.workers or according to predefined preconditions. . and it is not reusable by any other process or subprocess. Parent topic:Modeling processes Related information: Business process definitions (BPDs) Modeling events Declaring and passing variables Service types 36 . .Creating a user attribute definition You can associate unique capabilities or qualities with one or more users by creating user attribute definitions. 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. Click Save in the main toolbar. Parent topic:Creating a business process definition (BPD) 37 . 4. 8. If you do not specify a default lane team. if you move the task to a non-system lane. the initial assignment for the task is the default lane team. To reorder lanes with respect to one another. 3. Before you begin To perform this task.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. 2. In the Properties view. indicating that activities within it are to be completed by an IBM Business Process Manager system. any new tasks in the system lane are created as system tasks by default. Although you can create a system task in nonsystem lanes. Optional: You can also create a lane as a system lane. After a system task is created. 6. enter a name for the lane. Open the Process Designer desktop editor.When a user task is added to this lane. 7. select the lane in the diagram then select Is System Lane in the Properties view. you must be in the IBM® Process Designer desktop editor. Drag a lane from the palette and drop it onto the diagram. for example a lane associated with a team. A lane is the container for all the activities to be carried out by a specific team or by a system. it retains a system task type. Procedure 1. the default team is All Users. right-click a lane and select Move Lane Up or Move Lane Down. Optional: You can also associate a default team with the lane. Open a process application that contains a BPD. To make a lane a system lane. 5. Before you begin To perform this task. Click Save in the main toolbar. Procedure 1.Apply a top-down. What to do next After you add an activity to a BPD. enter a name for the activity. you can include activities that represent logical work that a specific team or a system completes. . 3. such as Submit job requisition. Open a process application that contains a BPD.Ensure that activities represent logical units of work that are assigned to a participant of a process. Drag an activity from the palette and drop it onto the diagram.Adding activities to a BPD In a business process definition (BPD). In the Properties view. Parent topic:Creating a business process definition (BPD) Related information: Implementing activities in a BPD 38 . 4. Open the Process Designer desktop editor. In the Designer view. follow these guidelines: . .Make multiple concurrent workflow steps that are assigned to one responsible role into one activity or task. 6. . you can change the type by selecting the activity and choosing the implementation in the properties. you must be in the IBM® Process Designer desktop editor. 5. left-to-right flow to your BPD so that it is easier to read. click the Diagram tab. About this task When you add activities. 2.Use verb-noun statements to label activities. the associated UCA carries out the required action when the event is triggered. click the Implementation option. drop the event onto the activity node. Other events must be part of the process flow. Drag the event from the palette. select the activity. attached intermediate events are Error events. You can attach intermediate events (timer. Select the event. 4. the event is attached. or at the end of a runtime process (as opposed to activities that are carried out by participants in the process). see Modeling events. Open a process application that contains a BPD. In the Trigger section. during. 5. Each event must be associated with a UCA. If the outline of the activity includes the event. By default. You can specify the trigger type of an event and represent the event with a meaningful icon in your process diagram. See the topic in the related tasks section. 2.Adding events to a BPD When modeling a process. Procedure 1. select Interrupt activity if you want the activity to close when the message is received. Before you begin To perform this task. Parent topic:Creating a business process definition (BPD) Related information: Creating an undercover agent 39 . 6. you might want to model events that can occur at the beginning. About this task An example of an event is a message received from an external system. For attached intermediate events. In the event properties. When you run the process. Open the Process Designer desktop editor. or the arrival of a message. an exception. To verify the attachment. message. 7. click the Diagram tab. Select the type of event from the available options. 8. For information about available event types and their triggers. The trigger determines the type of event that you choose to implement. Events in IBM BPM can be triggered by the passing of a due date. In the Designer view. If you want to create a boundary event by attaching an intermediate event to an activity. you can select or create an undercover agent (UCA) to attach to the event. 3. you must be in the IBM® Process Designer desktop editor. 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. 40 . 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. Before you begin To perform this task. When you are finished establishing the process flow. you must be in the IBM® Process Designer desktop editor. Continue creating sequence flows as needed. B. Open a process application that contains a business process definition (BPD) in the Designer view. The Sequence Flow tool connects the two items. 4. click the first modeling construct (normally the start event). Open the Process Designer desktop editor. the first one you add is the default sequence flow. Select the sequence flow in the diagram. specify the condition under which the process execution follows this sequence flow.Modeling process execution paths by using sequence flows Use sequence flows to connect activities and other modeling constructs to establish the process flow. Subsequent sequence flows that originate from the same construct are only followed under certain conditions. 6. 3. 2. 5. To specify the conditions under which a nondefault path is followed: A. 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 . In the Behavior section of the Properties view. From the palette. If more than one sequence flow leaves the same modeling construct. and then click the construct that follows the start event in the process flow. Procedure 1. click to select the Sequence Flow tool. In your process diagram. determining branching and merging of the paths that a runtime process or case instance can take. You can model the following types of gateways in your process or service flow diagram: Table 1. diverging gateway when you want the process to follow all available paths. Use downstream of an inclusive diverging gateway to converge multiple paths into a single path after all the active paths completed their runtime execution. Otherwise.Converging and diverging flows Gateways control the divergence and convergence of a sequence flow. The process or case cannot proceed until a valid answer is provided. About this task You can think of inclusive and exclusive gateways as questions that are asked at a particular point in the flow. diverging gateway when you want to follow one or more available paths based on conditions that you specify. which act as gates.Note:Case management functions are only available if you have IBM BPM Advanced with the Basic Case Management feature installed. The inclusive join looks upstream at each path to determine whether the path is active. The question has a defined set of alternative answers. it passes the token through without waiting. which are evaluated before the flow is allowed to proceed. in which case it waits. Use a parallel. You can model questions by using JavaScript conditions. Types of gateways that can be modeled in process diagrams Component icon Gateway type Parallel (AND) Inclusive (OR) 42 Description Use a parallel. converging gateway when you want to converge all available paths. Use inclusive. . depending on a condition. such as the receipt of a message or timer event. support for gateway implementation is provided for exclusive gateways only. Restriction: In human services. the process follows the default sequence flow. To add gateways to a process or human service diagram: Procedure 1. A specific event. Drag a gateway from the palette onto the diagram. An event gateway must be modeled a certain way as described in Modeling event gateways. as described in the following procedure.When you model inclusive and exclusive gateways. The default sequence flow is the first sequence flow that you create from the gateway to a following activity. 43 . see Example gateways. but you can change the default sequence flow at any time. if all conditions evaluate to false. Note: The exclusive gateways are the only gateways that can be implemented in human services.Exclusive (XOR) Event Use to model a point in the process or service flow execution where only one of several paths can be followed. determines the path to be taken.After you drag a gateway from the palette to your diagram. For more information about implementing inclusive and exclusive gateways. you can choose any of the available gateway types. . Be aware of the following when using gateways: . Use to model a point in the process execution where only one of several paths can be followed. For more information. or to model a point in process execution when the token for one of several incoming paths is passed through the gateway. depending on events that occur. see Implementing exclusive gateways in client-side human services. see Modeling event gateways.2. The default sequence flow is the first sequence that you create from the gateway to a following activity. B. Parent topic:Creating a business process definition (BPD) 44 . The other fields described in the following table are optional:Table 2. For each outgoing sequence line. 3. reorder the lines until the one that you want is designated the default. provide the path name for the image that you want to use. 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. Enter a description of the gateway. A. 7. click the Implementation tab. Click the gateway in the diagram. Configure the implementation for the gateway. Ensure that the type of gateway you want to implement is selected from the list. For inclusive and exclusive gateways. Note: A default sequence flow does not have a condition. If you want to use an icon other than the default provided by IBM® Business Process Manager.) 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. This option is not applicable to exclusive gateways that are implemented in human services. see Example gateways. 5. you can change the default flow by reordering the sequence flow in the implementation properties. Clear this check box if you do not want the name displayed in the diagram. In the box that displays over the gateway. a condition (in JavaScript) is required that controls whether the path is followed. The preceding table describes the types of gateways available. Click Save in the main toolbar. 6. For event gateways. click the list and select a gateway type. Create the necessary sequence flow to and from the gateway. This option is not applicable to exclusive gateways that are implemented in human services. For a gateway. (For more information about the types of conditions that you can define. In the Behavior section of the general properties. type a name for the gateway. If not. 4. and then click the General option in the properties. Note: If you want complex expressions to be used in gateway definitions. Review the following samples to learn more about exclusive and inclusive gateways. named Need GM Approval?.Restriction: Support for gateway implementation in human services is provided for exclusive gateways only.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. When modeling processes or case instances in IBM® Business Process Manager. the first gateway. The approval options are then shown under the Decisions section. which does not have a condition. . you have several options for implementing gateways. the flow follows the default sequence flow. The flow follows the first condition that evaluates to true. and then select Advanced Editors. JavaScript conditions that you define for the sequence flows that emerge from the gateway determine which path is to be followed by the flow. . you might have two exclusive gateways in a BPD diagram. In the sample and tutorial. click File > Preferences. 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.Sample exclusive gateway in a BPD . expand IBM BPM > Capabilities > IBM BPM Advanced Features. you can enable an advanced editing feature in your preferences so that complex expressions can be entered and customized. click the gateway in the BPD diagram and then click the Implementation option in the properties.For example. In the Implementation properties. 45 . The default preference settings do not have the advanced editing feature enabled. you must declare variables for that BPD. you must specify the JavaScript conditions that determine the path to be followed by the service flow. To see how this works. If all conditions evaluate to false. as described in Declaring and passing variables.To implement an exclusive gateway in a client-side human service.Example gateways The following samples illustrate how to model several types of gateways. as described in Implementing exclusive gateways in client-side human services. To enable the advanced editing feature.To implement an exclusive and inclusive gateway in a business process definition (BPD). decisions are evaluated from top to bottom. See Converging and diverging flows to understand the available options and to see a sample implementation of a parallel gateway. determines which path to follow based on whether the submitted job requisition requires approval. . The approval information is then shown under the Decisions section.The following example shows the implementation of an exclusive gateway in a human service.Remember: To enable the advanced editing feature in your preferences. JavaScript conditions that evaluate to true or false are defined in the implementation 46 .currentPosition. . and then click the Implementation option in the properties.local. click the GM Approved? gateway in the BPD diagram to select it.Sample exclusive gateway in a human service . the process follows the default path to the Find job candidates activity. the process follows the default path (Rejected path) to the Notify hiring manager activity. The Approved --> proceed to HR path is followed to the Find job candidates activity only when the tw.local.requisition. To model the exclusive gateway in the service flow.gmApproval variable is equal to "Approved". If a requisition is not approved. The second gateway. This logic ensures that those requisitions from Hiring Managers for new headcount are approved by General Managers before HR processing. This logic ensures that those requisitions that require approval are approved before HR processing. expand IBM BPM > Capabilities > IBM BPM Advanced Features. named GM Approved?. and then select Advanced Editors. Notice in the BPD diagram that the default path is marked with a forward slash (/). To see how this works. The Approval required path is followed to the Approve/reject requisition activity only when the tw. click File > Preferences. If a position is not new. determines which path to follow based on whether a new position is approved.positionType variable is equal to "New". Note that the default path is marked with a forward slash (/) sign in the diagram. under Decisions. The default sequence path is selected in the Default Flow list. For example. you want activities 1 and 2 to be completed. and you want to follow one or more available paths based on conditions that you establish. The sequence flow to Coach2 evaluates to false. Note: Inclusive gateways can follow a maximum of n-1 paths. if you model a conditional split with three paths. Sample inclusive gateway Use an inclusive gateway in a BPD when you need to split or diverge the process along more than one path. it follows the default sequence path. only activity 3 is needed. the process can follow two of those paths. So. suppose that you want to model a process where the steps are different based on whether the customer type is new or existing. if all conditions evaluate to false. A default sequence path is also specified in the Default Flow list. 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. and is followed to the Coach1 activity. For new customers. The flow follows the first condition that evaluates to true or. 47 .properties of the gateway. Restriction: Support for implementing inclusive gateways in human services is not provided. For existing customers. with no JavaScript condition associated with it. only one available path is followed from the gateway. The inclusive split gateway in the preceding example determines the path or paths to follow based on the type of customer that is processed. . .customerType variable is "New". the path to activity 2 is also followed.If none of the preceding conditions evaluate to true. you are able to run two separate activities for new customers and a different activity when the customer is an existing one.With exclusive gateways.If the value of the tw. Parent topic:Creating a business process definition (BPD) 48 . With inclusive gateways or splits like the one described in the preceding example.local. the path to activity 3 is followed. Using this logic.customerType variable is "New".local. one or more paths from the gateway can be followed. the path to activity 1 is followed.If the value of the tw. The conditions for this split are configured in the implementation properties for the gateway as follows: . 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..Table 1. choose System Task and select or create an Integration service to implement the task. 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. you must be in the IBM® Process Designer desktop editor. Select this option if an activity is to be completed by an automated system or service. For example. if an activity requires that managers enter employee data. such as a database. Building a client-side human serviceBuilding a heritage human service Service types . if an activity requires integration with an external system..Implementing activities in a BPD Choose the implementation for each activity in your BPD and set the required properties. see Task types. 49 See. Before you begin To perform this task. choose User Task and select or create a clientside human service or a heritage human service to implement the task. Linked processes encapsulate logically related steps within a process while retaining the high-level view of the parent process. if you want Process Designer to implement an activity when a condition evaluates to true. 50 Service types Using JavaScript variables and objects inside Process Designer Subprocess types Working with linked processes . Choose this option if you plan to create a script to implement an activity. Steps in a subprocess can directly access business objects (variables) from the parent process. No data mapping is required. choose Decision Task and select or create a decision service to implement the task. a subprocess can be accessed and instantiated only from the parent BPD. However. For example. use a subprocess for those implementations that are limited to a single business process definition (BPD). unlike a linked process. A Script activity runs a Java™ script. and it is not reusable by any other process or subprocess. Use this option to encapsulate logically related steps within a parent process.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. Linked processes differ from subprocesses because they can be accessed and instantiated from processes other than a single parent process. You can implement an activity by using a linked process. Therefore. Tip: To learn how to make an activity conditional. Select this option if you are not ready to associate an implementation. When triggered. Use this option to create a temporary placeholder activity in your process diagram until an implementation is available. Select the activity that you want to use in the BPD diagram. It is triggered upon occurrence of a configured start event. 2. choose User Task if the implementation for the current activity is a human service with a coach.) Tip: To implement the task as either a client-side human service or a heritage human service. and then go to the Implementation properties. see Implementing a BPD activity as a human service. 4. Open a process application that contains a BPD. If you run a process that includes an activity with this option selected. (The preceding table describes each available option. 3. Open the Process Designer desktop editor. and can encapsulate steps that use those variables. For example. an event subprocess can either interrupt the execution of its parent or can run in parallel. the task completes immediately after it starts. such as a service. It has access to the business objects (variables) of its parent process. see "Configuring conditional activities".Event Subprocess None Use this specialized Modeling event subprocess to model subprocesses event-handling logic for a process or subprocess. Under Implementation. 51 . select an option from the displayed list. and it is not connected to other steps through a sequence flow. Procedure When the implementation that you want to use is created. complete the following steps to select it: 1. Hours.) You can also use the variable selector next to the text box to choose an existing variable from the library. 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. you must specify extra properties. (User Tasks only) In the Task Header section.mySubject#>) to express the subject. Select the required 52 . specify values as needed. Under Due In. Under Priority. Enable this option only when you do not want to store execution data (such as variable values) for viewing after the process finished execution. (When you choose Days. 6. Type an optional description. (The previous table provides instructions for creating implementations. audit data for the task is not retained by the Process Server. (System Tasks only) Select Delete task on completion if you want to run an automated service that does not require routing. Instead. IBM BPM removes the data for completed tasks to conserve space. click JS for options. select one of the default priority codes from the list: Highest. By default.local. High. as outlined in the following steps. A. When you select this check box. If the implementation does not yet exist. this option is disabled. you can use the text box after the list to specify hours and minutes. When a task is complete. enter a value in the text box and then choose Minutes. <#=tw. Normal (the default). such as a database.Tip: If you prefer to use a JavaScript expression with predefined variables to establish the priority settings. B. Restriction: Do not use JavaScript variable references in task narratives if you need the data to be available after the task completes. 7. or Days from the list. click New to create it.) If you choose System Task for your implementation option. You can also use the IBM BPM embedded JavaScript syntax to express the narrative. (User Tasks only) In the Priority Settings section. 8.5. specify the following properties: Table 2. Low. store the data items in another location. this option is disabled. Type a descriptive subject for the task that is generated in IBM Process Portal when you run the BPD. At run time. or Lowest. Click Select to choose the implementation from the library. By default. You can also use the IBM BPM embedded JavaScript syntax (for example. the variable reflects the specified value for the time period. the work schedule that is specified for the BPD is used.Implementing a BPD activity as a human service If an activity in the business process definition (BPD) is to be completed by a user. . select Automatically flow to next task if you want the next task in the sequence to run automatically. you can enter either a String (or String-generated JavaScript) or a JavaScript that returns a TWHolidaySchedule variable. C. Each holiday schedule is made up of a list of dates. leave the setting at (use default) as described in the preceding note. see "Setting the due date and work schedule for a BPD". For more information.Creating loops for a BPD activity When you want the runtime task that results from a BPD activity to be run more than once. Under Holiday Schedule. You can leave the Schedule. and Holiday Schedule fields set to (use default). D. select an option from the list.option from the list: Minutes. you can implement the activity as a client-side human service or a heritage human service. Under Timezone.) 9. IBM BPM assumes that the holiday schedule is appropriately specified. Timezone. or click JS if you prefer to use a JavaScript expression. or Days. If you choose JavaScript. you can select US/Pacific for users who work in California. you can create a loop. select the time zone that you want to apply to the tasks that result from the current activity. If you use a String. Under Schedule. For example. select 24x7 if you want 24 hours a day. If you use a TWHolidaySchedule variable. Hours. E. (Go to the System Data toolkit and open the TWHolidaySchedule variable to view its parameters. 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 . If you do. (User Tasks only) In the Processing Behavior section. IBM BPM looks up the Holiday Schedule by name according to those rules. seven days a week to be the time period in which the resulting tasks from the current activity can be due. For example. when you double-click the task in the BPD: . select User Task. From the corresponding list. Open a process application that contains a BPD. From the Implementation list. update the name of the user task as required.The Process Designer desktop editor opens if the task is associated with a heritage human service. 3. and then click Select next to Default Human Service.Implementing a BPD activity as a human service If an activity in the business process definition (BPD) is to be completed by a user. 4. 5. Before you begin To perform this task. select the client-side human service or the heritage human service to implement the user task. click New and complete the wizard steps to create the human service.Back in the Diagram view. 2. If the human service does not exist. About this task To implement the activity as a service: Procedure 1. you must be in the IBM® Process Designer desktop editor. 6. Open the Process Designer desktop editor. On the General tab. Select the activity that you want implemented in the BPD diagram. and then click Save. .The Process Designer web editor opens if the task is associated with a clientside 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 . you can implement the activity as a client-side human service or a heritage human service. and then go to the Implementation properties. Prerequisite: To create loops. IBM Business Process Manager provides several ways to create and implement loops. Since you can include JavaScript throughout your implementations. see Inspector reference. as described in the following table. you can include a script component in a service that iteratively processes records that you retrieve from a database until all records are processed. (For more information about tokens. When you want the runtime task that results from an activity to be run more than once. A simple-loop activity is run sequentially until the last instance of the activity is run. a single token is generated and used for each instance of the activity. Parent topic:Implementing activities in a BPD 55 . up to the loop maximum value that you specify. Table 1. in effect. In addition to implementing loops with scripts.Configuring a BPD activity for multi-instance loops Using multi-instance loops.Configuring a BPD activity for simple loops Follow these steps to configure a BPD activity for simple loops. you must be in the IBM Process Designer desktop editor. which.Creating loops for a BPD activity When you want the runtime task that results from a BPD activity to be run more than once. A multi-instance loop dynamically runs multiple unique instances of the same BPD activity sequentially or in parallel. When you run a BPD activity that is configured for multi-instance loops. When you run an activity configured for multi-instance loops. the required number of instances is dynamically created. you can configure loop behavior for that activity. For example. you can easily develop the logic required to repeat an action until a certain condition is true. you can dynamically run multiple unique instances of the same activity sequentially or in parallel. You can create simple loops and multi-instance loops in IBM® Business Process Manager. When you run an activity configured for simple loops. recycles the runtime task. . a unique token is created for each instance of the activity. Loop types available for loop configuration Loop type Simple loop Multi-instance loop Description When you model a BPD activity with simple loops. you can create a loop. a unique token is created for each instance of the activity.) . the activities that you add to your BPDs can be configured for simple and multi-instance loops. 56 . A condition is evaluated before any instances are created from the activity. Procedure 1. recycles the runtime task. click the variable icon to select it or type the variable name into the Loop Maximum box. Before you begin To perform this task. Select the activity that you want to configure in the BPD diagram. 6. Click the General option in the properties. This value sets the maximum number of instances that can be created at run time. A simple-loop activity is run sequentially until the last instance of the activity is run. If you declare a variable that can be used for this setting. which. When you run an activity configured for simple loops. 3. in effect. 4. Save your changes. In the Loop Condition box. the loop configuration does not occur. select the Simple Loop option from the Loop Type list. a single token is generated and used for each instance of the activity. do not define ad hoc actions for Process Portal users to start. Results When you configure an activity for simple loops. up to the loop maximum value that you specify. Open the Process Designer desktop editor. type an optional JavaScript condition to dictate the runtime loop behavior. 8. If you are using looping. If the condition is not met. the activity includes the indicator shown in the following image: Parent topic:Creating loops for a BPD activity 57 . Open a process application that contains a BPD. About this task When you model an activity with simple loops. you must be in the IBM® Process Designer desktop editor.Configuring a BPD activity for simple loops Follow these steps to configure a BPD activity for simple loops. 2. 5. type a value in the Loop Maximum box. the required number of instances is dynamically created. Under Simple Loop. Under Behavior. 7. Restriction: Ad hoc start events are not supported in simple loop activities. 8. In the properties. Under Behavior. Tip: For information about how to associate each loop activity instance with a specific item in a list. 4. When you run a BPD activity that is configured for multi-instance loops. you must be in the IBM® Process Designer desktop editor. Open a process application that contains a BPD. If you are using looping. select Multi-instance Loop from the Loop Type list. see Associating loop activity instances with different items. select the activity that you want to configure. 2. To specify a variable that can be used for this setting. In the BPD diagram. 6. Restriction: Ad hoc start events are not supported in multi-instance loop activities. 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. select General. 58 . type a value in the Start Quantity box. Procedure 1. Open the Process Designer desktop editor. 7. Before you begin To perform this task. select one of the following options: Option Run Sequential Description Resulting instances are run sequentially until the last instance of the activity is complete. click the variable icon to select it or type the variable name into the Start Quantity box. a unique token is created for each instance of the activity. This value sets the number of instances that are created at run time. 5. 3. From the Ordering list. do not define ad hoc actions for Process Portal users to start. you can dynamically run multiple unique instances of the same activity sequentially or in parallel. Under Multi-instance Loop. 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. For parallel ordering.Configuring a BPD activity for multi-instance loops Using multi-instance loops. counter] specifies which item to be retrieved from the list. select Cancel Remaining Instances.local. you might want to associate each instance with an order in the list. . the result is given back to the multi-instance loop. 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. again sequentially. 10.As a prerequisite.Loop content contains Human.step. The behavior is different when the task content contains server scripts only and when it also includes services. Then.system.Loop content contains server scripts only: If you specify only server scripts in the multi-instance loop task content. and at the end of all task instances the exit conditions are verified. where . Save your changes. Decision. type the JavaScript to implement that condition in the Complex Flow Condition box. for example. which ends all other still running loop instances. the condition is evaluated and the multi-instance loop task completes. if you have five instances of an activity and five orders in a list. then the tasks instantiate in parallel within their own thread. 9. if an exit condition is set. This variable is used in the built-in tw. In the example of the System service.Conditional Wait (Complex) Looping continues until the condition that you specify in the following step is met. a loop with Ordering selected to Run in Parallel. If you want active instances of the activity to be canceled when the preceding condition is met.ListofItems[tw. where [tw. Therefore. upon completion of the System service task.ListofItems.step. the various instances of the loop run sequentially.ListofItems.listLength JavaScript function. they all run to their end.You associate each activity instance with a specific item in the list by using the tw. tw. To set up the activity instance-item association. runs as follows: . .counter] JavaScript. Procedure 59 . you must already have defined a private variable that holds the list of items that you want to iterate through. For complex flow conditions. with a valid complex flow condition. For example.local.system. or System services: If the loop task content contains a Human. and Cancel Remaining Instance set to true.listLength calculates the length of the item list. the following key settings are required: . For example.local. or System Service. Decision. 11.The runtime behavior of a multi-instance loop depends on how its task is implemented. all instances run in sequence. local. On Data Mapping. or type the following input string: tw. enter tw. select Multi-instance Loop from the Loop Type list. refer to steps 7 and 8 in the procedure described earlier. 3.1. Under Multi-instance Loop.step. For the Ordering and Flow Condition settings.ListofItems[tw.listLength in the Start Quantity box. In the properties. select General. 60 .ListofItems. select the activity that you want to configure. 2.local.system. under Input Mapping. In the BPD diagram. 4. select. 7. 5.counter] 6. Under Behavior. Save your changes. you must start the Process Designer desktop editor. In the Behavior section of the properties. the team that is assigned to the activity is used. For instances that they own. The instance owners team and lane teams are authorized to perform actions that are related to an ad hoc activity. the All Users team is assigned to each lane in the BPD.Note: If the default team assigned to the lane that is currently used for activity is changed. they can reassign user tasks. You need a default lane assignment to ensure that any activities that are not otherwise routed have an automatic default assignment. and as instance owners in the Overview page of the BPD editor. members of that team can work on that task in Process Portal. 61 . set their due dates and the priority of tasks. In the BPD diagram. such as starting a manual activity. 3. click the lane in which you want to make the assignment. Procedure To assign a team of instance owners to a BPD: 1. disable.Assigning teams to BPDs and lanes Assign teams of users that can start activities. to lanes. 3. You can assign a team of instance owners for a BPD. 2. members of the team that is assigned to the lane or members of a task-specific team can work on the task. 2. If a user task implements an ad hoc activity. see Creating a team. The All Users team includes all users in the system who are members of the tw_allusers security group. or create a new team. For information about how to create a team. the team filter service definitions are removed from the Assignments tab. If a team is assigned to a user task activity. To assign teams to lanes: 1. and can start. If a team is assigned to a lane. and enable ad hoc activities in the BPD. or you can assign teams for individual activities and lanes. About this task You can assign teams to activities that are implemented as user tasks (including ad hoc activities). Teams that are assigned to activities and lanes determine which users can work on tasks in Process Portal. Open the Process Designer desktop editor. select a team for Instance owners. Before you begin To perform this task. Choose the team from the library. By default. In the BPD Overview. and teams that can work on activities in Process Portal. Members of the instance owners team can start the task in Process Portal. Open the process application that contains the business process definition (BPD). click Select to choose the team that you want to use as the default team for this lane. You can use this default team for running and testing your BPD in the Inspector. If both a user task activity and the lane in which it is contained have teams that assigned to them. members of that team can work on all the tasks that are part of that lane. Click Save in the main toolbar. see Assigning teams to BPD activities 1.To assign teams to activities. Parent topic:Creating a business process definition (BPD) 62 . 4. 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). Procedure 1. Open the Process Designer desktop editor. If you select this option. Assigns the runtime task according to the policy that you establish. Open a process application that contains a business process definition (BPD). Assigns the runtime task to a team. Go to the Assignments page in the properties view. 3. you can designate the users who receive the runtime task by using the Assignments page in the properties for that activity. choose one of the following options:Table 1. 5. In addition. If you select this option. you must be in the IBM® Process Designer desktop editor. you can use a team filtering service to remove unsuitable users from the team. you can either specify a static team or use a team retrieval service to dynamically select a suitable set of users. 63 . Assigns the runtime task to an ad hoc list of users. 2. Before you begin To perform this task.Assigning teams to BPD activities For any activity with a service implementation. From the Assign To list. Click an activity in a BPD diagram to display its properties. you can use a team filter service to dynamically eliminate users from being assigned to the activity. About this task Note: Assignment options are available only for those activities with a BPM service implementation. 6. see Creating a team. tasks must be assigned to a Team or a team Lane. Important: To show up in the Team Performance dashboard. for example tw. and complete the team properties. To define a new team. If you want to use a team filter service to eliminate certain users before the user distribution is applied. Optional: From the Experts Team list.user. damageAssessors. 8. For each required service variable. If you want to specify a fixed team name or a team that is not defined yet. C. enter the name as a literal value. B. A.local. 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).Custom (Deprecated) Assigns the runtime task according to the JavaScript expression that you provide in the corresponding field. 7. select the team that you want to associate with the selected activity. for example.local. click Select. If the team filter service that you selected or defined requires parameters from the application. specify the name of the variable. then choose a team from the list. click New. complete the following steps. If you select New. If you want to select an existing team. If you want the team to be selected by the value of a local or environment variable. a Team Filter Service Input Mapping section is displayed. The JavaScript expression produces results such as USER:<user_name> or ROLE:<group_name>. provide a name. enter the corresponding process variable name. If you selected Assign ToTeam you must assign a team. 64 .dynamicTeamName. A. Optional: If you selected Assign ToTeam or Assign ToLane the Team Filter Service section is displayed. either click Select to select an existing team filter service or click New to define a new one. B. tw.estimatedClaimAmount or tw. D.isWeekendCrew?"ROLE:Week endManagers":"ROLE:Managers". For more information about the team properties. for example tw. click the variable selection icon next to the field. More valid expressions can be chained together to produce a complex JavaScript expression.id . To assign a Team Filter Service. perform Setting up a team filter service.Note: Complex JavaScript expressions can be typed in or pasted into the Expression field and can be customized as required.local. for example. Tasks that are assigned to the deprecated options are not displayed on the Team Performance dashboard.system. To select one or more variables for your expression. 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. . the runtime task is routed to the user who started the BPD. IBM BPM assigns to users in a round-robin fashion. choose one of the following options:Table 2. you can define a team retrieval service that dynamically returns a set of users and managers. is to establish a routing policy. From the potential users who can receive the runtime task. you establish rules to determine the recipients of the activity as a runtime task. In this case. regardless of presence. From the User Distribution list. . Parent topic:Creating a business process definition (BPD) 65 . IBM BPM assigns to the users who have the fewest number of open tasks. Assigns the runtime task to the user who completed the activity that immediately precedes the selected activity in the swimlane. . .9. User Distribution Option None Last User Load Balance Round Robin Description IBM BPM assigns the runtime task to all potential users (the default setting).Defining rules with a routing policy (deprecated) When you establish a Routing Policy for a BPD activity.Assigning an activity to a dynamically retrieved team If you do not want to assign an activity to a static team. For example. IBM BPM assigns each task (created by each process instance) in a series .Setting up a routing policy (deprecated) One of the options when routing the runtime tasks that are generated by activities. if the users in the Call Center team must receive the runtime task.to one user in the team after another.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. From the potential users who can receive the runtime task. 4. About this task You can define a new team retrieval service either when you define a team. 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. From the Assign To list. or when you assign an activity to a team. Procedure If you are working with a business process definition (BPD). then follow the instructions described in Setting up a team retrieval service. you must open the Process Designer desktop editor. Go to the Assignments page in the properties view. To assign the activity to an existing dynamically defined team. Results The team's members are determined dynamically by the appropriate team retrieval service. Open a process application that contains a BPD. provide a team name. and want to assign an activity to a dynamically retrieved team. 5.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. Before you begin To perform this task. complete the following actions. click Select then select the name of the dynamically defined team. Open the Process Designer desktop editor. click New. 6. 2. 7. To assign the activity to a new dynamically defined team. you can define a team retrieval service that dynamically returns a set of users and managers. 1.Assigning an activity to a dynamically retrieved team If you do not want to assign an activity to a static team. Parent topic:Assigning teams to BPD activities 66 . select Team. if you choose a variable called customer (String) in the preceding step and that variable holds customer names.For example. click Add a column to select the variable to use to begin specifying conditions. Before you begin To perform this task.. 8. Open the Process Designer desktop editor. 4. Enter the value to compare to the second variable. When you establish routing rules. you create a table in which each column represents a variable and each row represents a rule. enter the value to compare to the variable.The following examples illustrate the syntax for possible values in the variable columns: Table 1. About this task When you define a policy. such as only those users who have a previously defined user attribute. From the Assign To list. Routing conditions Enter.. Go to the Assignments page in the properties view. Under Routing Conditions (If).Setting up a routing policy (deprecated) One of the options when routing the runtime tasks that are generated by activities.When defining routing conditions. 9. the users who receive the runtime task are determined by the conditions that you specify. you create specifications that determine who receives the runtime task. select Adv. Note: The activity that you choose must already have an attached service. is to establish a routing policy. 6.To 67 . Open a process application that contains a business process definition (BPD). The exact string. you must be in the IBM® Process Designer desktop editor. If you want to add another variable to the routing condition. click Add a column and choose a variable from the displayed list.. To match. ok (no quotation marks) Any number greater than 100 Any number less than 100 All numbers except 3 "ok" >100 <100 !=3 10. If you want to establish advanced routing rules. you must declare variables for your BPD.. select Routing Policy (Deprecated). Procedure 1. 3. In the first field in row 1. From the displayed list. Open the diagram of your BPD and select the activity that you want to route. enter a customer name in the field. choose the variable for which you want to specify a condition. 5. Before you can configure a routing policy. 2. 7. If you have multiple teams defined in your current process application. and then click Remove. you select one of those teams from the menu.establish rules. and see Deprecated: Defining rules for instructions. IBM BPM evaluates the conditions in the table from top to bottom. Parent topic:Assigning teams to BPD activities 68 . Swimlane. What to do next When you define routing conditions. which means that the runtime task is routed to the team assigned to the swimlane in your BPD. If you want to remove a rule after you define it. IBM BPM assigns the activity to the default assignee. the Assign To field in the routing table shows the default assignee. If you do not select Adv. 11. Swimlane. click the bullet before the rule that you want to remove. click Advanced Lane Participant in the Assign To field in the routing conditions table to display the rule or rules for that routing condition. click Add Rule in the Advanced Assigned To (Then) section of the Routing properties. Note:IBM Business Process Manager creates only one set of rules under Advanced Assigned To (Then) for the entire Routing Conditions table. Under Advanced Assigned To (Then). IBM BPM implements the first condition that matches. If no conditions match. Defining rules with a routing policy (deprecated) When you establish a Routing Policy for a BPD activity. you must be in the IBM® Process Designer desktop editor. the runtime task is assigned to users who match at least one of the specified rules. Open a process application that contains a business process definition (BPD). 69 . 5. Selects users based on user attributes. click Add a column. select Adv. About this task Using rules. which ensures that activities are routed to the appropriate individuals. Under Routing Conditions (If). In the table. If you choose all. If you choose any. Before you begin To perform this task. Selects users who match a particular expression that you provide. 6. Open the Process Designer desktop editor. 7. Click an activity in the BPD. Under Advanced Assigned To (Then). your task assignments can be dynamic. click all in the following statement: Advanced Lane Participants are users who match all of the following rules: Choose all or any. Selects users according to group membership. you can choose from the following rule types: Table 1. 8. The Routing Conditions (If) section becomes available. 4. Available rule types Rule type Swimlane Participant Rule User Attribute Rule Expression Rule Description Routes activities to users based on whether they are the default lane participants. IBM Business Process Manager assigns the task to the swimlane for the rule to which this Advanced Assignment applies. In the Properties page. In the Assign To list. 3. click Assignments. Procedure 1. the runtime task is assigned to users who match all specified rules. and select the variable for which you want to add the condition. select Routing Policy (Deprecated). 2. If none of the conditions that you specify are met. When defining rules. The Advanced Assigned To (Then) section is populated. you establish rules to determine the recipients of the activity as a runtime task. 10. Table 2.For a User Attribute Rule.Recipient The Add Decision.. supply the required input for the following specification: Who have an attribute select user attributeequal toenter value. equal to 70 .For a Swimlane rule. Table 4. option adds other rules to the list.loanAmount . Supply the necessary information for the specified type of rule. or greater than or equal to. Click equal to to choose from: equal to. less than or equal to.For a Participant Rule. Click select team to choose a team from the library. Table 3.local. select team . not equal to. you can define the following Advanced Lane Participant group (team) rules in the group properties: Advanced Lane Participants are users who match all of the following rules: . supply the input that you want for the following specification: Who belong to the select team .Who match expression tw. Click Add Decision to choose the type of rule to add.local. . supply the required input for the following specification: Who belong to lane participant.Who have an attribute Level 1 Loans greater than tw. greater than. Input required for a User Attribute Rule Specification select user attribute Action Click select user attribute to select a user attribute definition from the library. less than. .9.Who belong to the Finance Managers group .For example. Input required for a Swimlane rule Specification belong Action Click belong to choose either belong or do not belong. Input required for a Participant Rule Specification belong Action Click belong to choose either belong or do not belong.. Input required for an Expression Rule Specification match Action Click match to choose either match or do not match. Be sure to surround any strings in the expression with double quotation marks. Be sure to surround any strings in the expression with double quotation marks. supply the required input for the following specification: Who match expression enter value. The variable or expression must evaluate to a specific user name.enter value Click enter value to display a field in which you can enter either anIBM BPM variable or a JavaScript expression that produces the value that you want to compare.For an Expression Rule. Table 5. . enter value Parent topic:Assigning teams to BPD activities 71 . Click enter value to display a field in which you can enter either an IBM BPM variable or a JavaScript expression that produces the value that you want to compare. Click the Assignments page in the properties view. Open the Process Designer desktop editor. Note: To assign activities to an ad hoc user list. In the Binding field. 3.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:Assigning teams to BPD activities 72 . select List of Users (Deprecated). 4. 5. to dynamically generate the user list. Before you begin To perform this task. About this task The ad hoc group or list of users is maintained while the process instance exists on the runtime Process Server. you must be in the IBM® Process Designer desktop editor. Procedure 1. 2. you can define a new complex variable that is a list (array) to pass the list of users from the service that generates the list to the activity to be assigned. upstream from the activity to be routed. create an activity with an underlying service. Open the diagram of your BPD and select the activity that you want to route. specify the variable that binds the list to the activity to be assigned.For example. Open a process application that contains a BPD. 6. The activity that generates the user list must include an output variable that binds the user list to the follow-on activity to be routed. From the Assign To list. .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.Implementing a conditional activity Complete the following steps to implement a conditional activity. . Parent topic:Creating a business process definition (BPD) 73 .Managing conditional activities by using the JavaScript API You can find and select conditional activities for runtime execution by using the following JavaScript API properties. The decision to skip or complete a conditional activity can be made by the runtime user or programmatically. based on scripted rules. If a wired conditional activity is turned into an ad hoc activity by deleting wires to and from the activity. and then select the Is Conditional option. Click the Condition tab in the properties. 2.system. 3. the activity is carried out only if previously selected. you can generate reports to show which activities are skipped and how 74 . a tracking point is created with SKIP appended to the name of the skipped activity. Note: If a script is present in the box. Before you begin To perform this task. the isConditional option becomes disabled. it overrides any human decision at run time to carry out or skip the activity. use preconditions. you must be in the IBM® Process Designer desktop editor. 4. Using this data. the activity is carried out. 5. Note:IBM Business Process Manager Performance Data Warehouse records data that can be used to analyze the conditional activities. If the runtime return value of the supplied script is true.Implementing a conditional activity Complete the following steps to implement a conditional activity. Select the conditional activity for execution by using one of the following options: Option JavaScript Set selected conditional activities Description Enter JavaScript in the available box.Restriction: The conditions tab is disabled for ad hoc activities (unwired activities). To set conditions for an ad hoc activity. click the activity that you want to make conditional. It returns a valid Boolean (true or false) value. In the BPD diagram. The diamond-shaped icon on an ad hoc activity indicates that the activity has a precondition. If the Is Conditional option is enabled and no JavaScript is entered in the box. When a conditional activity is skipped. Open the Process Designer desktop editor.selected ConditionalActivities property to set selected conditional activities. A tracking point is created in the Performance Data Warehouse TRACKINGPOINT views each time an activity is skipped. Open a process application that contains a business process definition (BPD).process. See Creating an unstructured (ad hoc) activity The activity in the BPD diagram includes a diamond-shaped icon to indicate that it is conditional. Use the tw. Procedure 1. Parent topic:Configuring conditional activities 75 .often those activities are skipped in a process instance. You can use this property to construct a Coach that specifies the conditional activities that you want to run in the current BPD instance.process. tw. Parent topic:Configuring conditional activities 76 .selectedConditio Returns a list of identifiers for the nalActivities conditional activities that are to be run at run time. tw. tw.step. tw.Managing conditional activities by using the JavaScript API You can find and select conditional activities for runtime execution by using the following JavaScript API properties.isConditionalActivi Determines wheter the current step is a tySelected conditional activity that is selected for execution.step.conditionalActiv Finds all conditional activities in a ities process definition (BPD).system.guid Returns the ID of the BPD. which is the output format from the conditional activity Coach described earlier.process.system. This property also accepts a comma-separated string of IDs. The following table lists the available JavaScript API properties.guid Returns the ID of the step or activity that is currently running. Table 1.system.system. You can set the value of this property by providing a list of conditional activity IDs to be selected. JavaScript API properties Property Description tw.system.process. Returns a list of items of the ConditionalActivity variable type. E. B. Select Properties > Implementation > Activity Behavior. you can also select is less than. . or is greater than or equal to. select Repeatable: The activity can be invoked multiple times. For example. Drag the activity from the palette to your process diagram. If the activity is started by the system. . If the activity can be run multiple times. or Linked Process implementations. 77 . select Hidden. The activity is required. select Yes. . To specify the conditions by selecting a variable. complete the following steps. In the next field. Tip: The choices that are available depend on the type of the variable that you selected. . is greater than. A. Click the variable selection icon to select from a list of variables. If preconditions must be met before the user or system can start the activity. for numeric. If you add any wiring to the activity.If the activity does not have to be completed for the process to complete. and time variables. or whether it is sufficient for any one of them to be true. If there are multiple conditions. and they can be defined as repeatable or to run at most once. date. Indicate how the activity is started. This is a background activity that users will not see.If the activity is started by the system. The Activity Behavior section is only displayed for unstructured activities that have User Task. 2.If the activity must be started manually by the user. either enter a literal value or the name of a variable. is less than or equal to. Specify the behavior properties of the activity. Indicate whether the activity must be completed. 1. 2. A. or click the other variable selection icon to select from a list of variables.Creating an unstructured (ad hoc) activity An ad hoc activity has no input wires and is started as required by knowledge workers or according to predefined preconditions. and must be hidden from users. D. and specify the conditions that must be met. In the next field. use the Match field to select whether all must evaluate to true. such as is equal to and not equal to. B. select No. Knowledge workers can start unstructured activities from the Activities section in the Process Instance details page in Process Portal. rather than by a predefined process flow.Important: Do not add any input or output wiring to the activity. Procedure To create an unstructured (ad hoc) activity. Such activities can be required or optional. select Manually by the user. Subprocess. the activity is no longer unstructured. C.If the activity must be completed before the process can complete. The activity is optional. use the default form. select There are preconditions that must be met before the activity can be performed. select the type of comparison that is required. a comparison operator. 1. and another variable or literal value. select Automatically by the process. F. C. 4. To return to the default form. and enter the JavaScript expression for the condition. Parent topic:Creating a business process definition (BPD) 78 . To add more conditions. click js again. click the add icon. .3.Example: Starting an unstructured (ad hoc) activity (JavaScript API) This example shows you how to start an unstructured (ad hoc) activity. click js to switch to the JavaScript expression form. To specify the conditions as JavaScript expressions. Refer to the description of the TWProcessInstance object in JavaScript API for IBM Process Designer.Process/case admin .ActivityListFilter(). use the findActivityInstanceByID() call to retrieve the instance of the activity.local. log.info("found process instance: " + pi). activitiyListProperties.info("querying for activity list .activities = pi.local.filters..piid). Retrieve a list of matching unstructured activities and their IDs on a TWProcessInstance object.activities). .retrieveActivityList(activitiyListProperties) log. activityListFilter.. the user must be a member of one of these groups: .object. var activitiyListProperties = new tw.ActivityListFilter(). var activityListFilter = new tw.object.info("activities found: " + tw.aiid = // get the id of the activity you want to start (and 'actions' contains 'ACTION_START_ACTIVITY') 2.filters = new tw.info("querying for piid: " + tw. log. Refer to the description of the 79 . log. On the ActivityListItem object there is a list of available actions for the current user (the user that executed the retrieveActivityList() call).local. var pi = tw.local.Example: Starting an unstructured (ad hoc) activity (JavaScript API) This example shows you how to start an unstructured (ad hoc) activity.listOf.system.. complete the following steps. Then call start(."). tw.BPM admin . activityListFilter).. activitiyListProperties.Process/case instance owner . When you have the ID of the unstructured activity.Set the hiddenFilter parameter to retrieve hidden activities. as well as the ID of the activity.insertIntoList(0.executionStateFilter = ["READY"].findProcessInstanceByID(tw.Default lane team of the corresponding lane An authorization check is performed by the REST API only when starting an unstructured activity.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.local. Before you begin To start an unstructured activity. tw.) to start the instance. Procedure To start an unstructured (ad hoc) activity. .ActivityListProperties().object.piid). 1. aiid).findActivityInstanceByID(tw.TWBPDSystemNamespace object in JavaScript API for IBM Process Designer.start().info("starting activity with id: " + tw. var ai = tw.info("querying for aiid: " + tw.aiid).aiid). Parent topic:Creating an unstructured (ad hoc) activity 80 . log. The optional parameter taskOwnerUserId reassigns the task to the specified user id.local.local.local. This feature works only for unstructured activities with a user task implementation.system. Refer to the description of the ActivityInstance object in JavaScript API for IBM Process Designer. ai. log. a subprocess can be accessed and instantiated only from the parent BPD. Table 1. 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. Steps in a subprocess can directly access business objects (variables) from the parent process. Types of subprocesses that can be modeled in a business process definition Implementation Description Characteristics 81 Variable scope . or you can drill into the subprocess for a more detailed view of its contents. 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. providing a simplified. For example. Their characteristics are described in the following table. double-click the subprocess activity in the parent. To go back to the parent process from within a subprocess or event subprocess. high-level view of the parent process. Subprocesses can contain swimlanes that are distinct from the parent process. You can view a subprocess as a single activity. However. and it is not reusable by any other process or subprocess. use the menu above the canvas. No data mapping is required. unlike a linked process. A subprocess can be embedded within another subprocess. Like other activities. use the navigation in the upper left corner of the diagram. There are three types of subprocesses that you can model in a BPD. To drill down into a collapsed subprocess and view the contents.Subprocess types Subprocess is an option for encapsulating logically related steps within a parent process. A subprocess represents a collection of logically related steps contained within a parent process. To return to a parent process from a linked process. with subprocesses contained within other subprocesses. Linked process A call to another reusable process. 82 .Activity names must be unique with respect to the top-level process activities.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. Inherits variables from the parent process and can contain local private variables visible only within the subprocess. therefore contain multiple data mapping is start events. with an implementation type of None. The process called Variable data is by the linked local to each process activity can process. and all other subprocesses and event subprocesses under the same toplevel process. but required to pass must contain at data into and out of least one start event the linked process. variable names must be unique throughout the entire subprocess hierarchy.Subprocess A non-reusable subprocess that exists only within the parent process. Each subprocess must contain at least one start event with an implementation type of None. Working with linked processes A process can call another process through a linked process activity. If you group these steps together in a Create Customer Account process. They are unlike other subprocesses in that they are not connected to other activities in the process by incoming or outgoing connections. Inherits variables from the parent process and can contain local private variables visible only within the subprocess.Modeling non-reusable subprocesses A subprocess is a logical collection of activities that exists only within its parent process. When the linked process activity is triggered at run time. the steps for creating a customer account might be common to several different processes.Variabl e names declared in an event subprocess cannot be the same as variable names declared in any of its parent processes. the linked process is run. If there are multiple layers of embedding. Grouping related process elements in a subprocess simplifies the view of the process. variable names must be unique throughout the entire subprocess hierarchy. After the linked process is completed. . you can use linked process activities to call this process from all processes that require it. 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. . 83 .Event subprocess A specialized type of non-reusable subprocess that is not part of the normal sequence flow of its parent process. instead of in a subprocess. and which might occur zero or many times during the execution of the parent process. with event subprocesses contained within other subprocesses. A subprocess hides the complexity of individual step details until the subprocess activity is expanded. but are instead triggered by an event or timer. and all other subprocesses and event subprocesses under the same top-level process. and are not reusable outside of that process. you can reuse that process in other processes that share that set of activities. the parent process resumes execution. Boundary events are not supported on an event subprocess. Must contain a single start event. When you group together related activities in a separate BPD. For example.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. Parent topic:Creating a business process definition (BPD) 84 . However. drag elements from the palette onto the canvas. Subprocesses must contain at least one start event with an implementation type of None. 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. swimlanes or phases that you add to your subprocess are independent. Select the subprocess activity in the parent process and set the repeating behavior in the General tab. B. They are not part of the swimlanes and phases that are contained in the parent business process definition. Procedure 1. and enter the name of the activity in the highlighted box. use the 85 . 3. Drag an activity from the palette onto the diagram area. you can Modeling subprocess data that are only available to the subprocess (and any subprocesses it contains). The subprocess expands in the editor. What to do next In a business process. 4. For a business process. By default. The visualization of the activity in the diagram is updated to reflect the subprocess activity type. Names of activities that you create in your subprocess must be different from the names of activities in the top-level process. A. In the Implementation tab of the Properties view.Modeling non-reusable subprocesses A subprocess is a logical collection of activities that exists only within its parent process. Double-click the subprocess activity to add elements to the subprocess. For a business process. Grouping related process elements in a subprocess simplifies the view of the process. Like other activities. 2. C. Subprocesses have access to all of the variables that are defined in the parent process. your new subprocess contains a start event and an end event. to return to the parent business process definition. You do not need to map data to pass data into or out of the subprocess. you can configure your subprocess to run the subprocess steps multiple times. For a business process or case type. select Subprocess. The names must also be different from any subprocess under the same top-level process. A subprocess hides the complexity of individual step details until the subprocess activity is expanded. open the parent business process definition (BPD) in the Process Designer. 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. About this task Linked processes encapsulate logically related steps within a process while retaining the high-level view of the parent process. you must map the inputs and outputs of your linked process to the inputs and outputs of the linked process activity in the parent. However. Specify another process to call during the execution of your process. 3. If you want to pass data into or out of a linked process activity. you can use linked process activities to call this process from all processes that require it. and choose the business process definition. 5. select Linked Process. linked processes differ from subprocesses because they can be accessed and instantiated from processes other than a single parent process. 4. continue to specify this new process definition. or return to the parent process. In the Implementation tab of the Properties view. For example. Variables in a linked process activity are local to the linked process. Drag an activity from the palette onto the diagram area. Linked process activities are represented in the process diagram by an activity element with a thick border and an expandable subprocess marker. the linked process is run. B.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. In the editor. Complete one of the following steps in the Data Mapping tab of the Properties view for the linked process activity: . the parent process resumes execution. . The visualization of the activity in the diagram is updated to reflect the Linked Process activity type. In the parent process. connect the linked process activity to other elements in the process flow. . the steps for creating a customer account might be common to several different processes. When you group together related activities in a separate BPD. When the linked process activity is triggered at run time.To create a reusable process: A. you can reuse that process in other processes that share that set of activities. 2.You can also Calling a linked process dynamically by using a variable defined in the parent process. Click New. linked processes were known as nested processes. instead of in a subprocess. and type the name of the activity in the highlighted box. click Select. In previous product releases. Open the parent business process definition (BPD) in the Process Designer.To select an existing process. Enter a name for the new process and click Finish. . use auto- 87 . If you group these steps together in a Create Customer Account process. After the linked process is completed. Procedure 1. 6. Calling a linked process dynamically When you use a linked process as the implementation for an activity. . Parent topic:Subprocess types 88 .mapping to have the inputs or outputs of the linked process automatically mapped to variable defined in the parent process. depending on your needs. .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. you can use an advanced option in the implementation properties to supply a predefined variable to dynamically call one of many linked processes. the Data Mapping tab for the activity in the parent process includes those variables. Open the parent BPD in the Process Designer.Because you already created the input and output variables for the linked process. . 7.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 map variables from the parent process to the linked process. It cannot drill down into dynamically linked processes that are called by the process at run time. follow the steps described in Working with linked processes. the name of the invoked business process definition (BPD) must be prefixed with a double slash (//). 4. you can use an advanced option in the implementation properties to supply a predefined variable to dynamically call one of many linked processes. Your parent process must also include the logic to determine the value of this variable at run time. To meet this requirement. In order for the search to be started at the beginning of the dependency chain (in PA1).Dependencies might exist between process applications and toolkits. 89 . 3.Calling a linked process dynamically When you use a linked process as the implementation for an activity. For example. 5. select the Linked Process menu option. . Click Select to choose one of the predefined linked BPDs from the library. 2. If a BPD in TK1 invokes a BPD dynamically without the double slash prefix. 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). and then click the auto-map icon in the upper-right corner of the Output Mapping section. click the auto-map icon in the upper-right corner. Click the activity that you want to work with in the BPD diagram. in TK1 and TK2. depending on your needs.Create a variable of type String in the parent process to hold the name of the linked process that you want to run. 6. complete the following steps: Procedure 1. as well as between toolkits and other toolkits. the parent process can include logic to set the value of this variable based on user input. Under Implementation. To configure an activity to dynamically call one of many potential linked processes. which in turn might depend on Toolkit TK2. ProcessApp PA1 might depend on Toolkit TK1. it will find only BPDs down the dependency chain (that is. the variables in all potential linked processes must be the same. but not in PA1). Under Input Mapping. complete the following tasks first: . Click the Data Mapping tab in the properties. This creates a dependency chain: PA1 -> TK1 -> TK2. For example.You must initially select one of the predefined linked BPDs for the dynamic configuration to function properly. About this task To use the dynamic option for a linked process. Click the Implementation tab in the properties. 8. Click the Implementation tab in the properties. Parent topic:Working with linked processes 90 . 11. the value of this variable cannot be null and it must exactly match the name of an existing BPD. 10. Click the indicator next to the Processing Behavior section heading to expand the section. Save the configuration.Note: At run time. 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. 9. About this task The event subprocess is a specialized subprocess that you can use to model eventhandling logic for a process or subprocess. For example. It has access to the business objects (variables) of its parent process and so can encapsulate steps that use those variables. an event subprocess can either interrupt the execution of its parent or it can run in parallel. but are instead triggered by an event or timer. They are unlike other subprocesses in that they are not connected to other activities in the process by incoming or outgoing connections. Event subprocesses are similar to other subprocesses in that they are contained within a parent process. It can have any of the following implementation types:Table 1. is received by the event subprocess and triggers a sequence of activities. which contains activities to order more stock or to check supplies at other locations. When triggered. The out-of-stock event in the parent process triggers the start event in the event subprocess. and as a result it is not connected to other steps through sequence flow. An event subprocess can have only one start event.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. such as an out-ofstock message. It is triggered upon occurrence of a configured start event. A message start event might be used in a situation similar to the situation described previously.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. an event subprocess can be used to handle an out-of-stock situation that arises during an order-fulfilment process. and are not reusable outside of that process. . The start event implementation is represented visually in the event subprocess activity in the parent process. For example 91 .Modeling event subprocesses Event subprocesses are triggered by an event that occurs in the parent process. You can use event subprocesses to handle exceptional process flows within your process. where a message. Event subprocess implementation types and visualizations Start event implementation type Event subprocess visualization Error Message Timer . if a requested item cannot be located within a certain amount of time. and might have multiple instances that run in parallel. event subprocesses with an interrupting start event terminate all activities in the parent process. for example. In the Implementation tab of the Properties view. unless the parent is terminated by a terminate end event. 5. 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. Select the start event and. from the Implementation tab in the properties view. . 4. for example. select a new implementation type from the list. When you select this property. the event subprocess might run several times during the execution of a process. A parent process cannot complete until all active event subprocesses are complete. new event subprocesses are assigned an error start event. errors that arise during the event subprocess execution. Drag an activity from the palette onto the diagram area. A terminate end event in an event subprocess terminates only the activities that are contained within that event subprocess. 8. event subprocesses can themselves contain event subprocesses. 6. Drag elements from the palette onto the canvas. To handle exceptions within an event subprocess. Error start events can be triggered only from within the parent BPD or its subprocesses. To configure an event subprocess to be repeatable. The visualization of the activity in the diagram is updated to reflect the event subprocess activity type. and type the name of the activity in the highlighted box. Open the parent business process definition (BPD) in the Process Designer. To add an event subprocess to your BPD: Procedure 1. The start events for event subprocesses can be interrupting or non-interrupting. the order fulfilment system is non-responsive. select Event Subprocess. To change the start event type and properties and to add activities to the event subprocess. Activities in an event subprocess with a noninterrupting start event run in parallel with the parent process. Boundary events cannot be attached to event subprocesses.An error start event might be triggered when something goes wrong in the 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. When triggered. 92 . looping behavior is not supported for event subprocesses. 7. 2. select Repeatable? on the Implementation tab. double-click the event subprocess activity to expand it. 3.Note: Unlike subprocesses. Note: Error start events in an event subprocess always interrupt the parent process and cannot be set to non-interrupting. You can specify whether the start event of the event subprocess is interrupting or non-interrupting by selecting or by clearing Interrupt Parent Process. the out-ofstock subprocess can be triggered by a timer start event. By default. which are not visible to the parent BPD. event subprocesses have access to the data of the parent process. You can also declare private variables within the event subprocess itself. What to do next To return to the parent BPD. Data mapping is not required to pass data into or out of the event subprocess. use the navigation in the upper left of the canvas. See Modeling subprocess data. Like subprocesses.9. Parent topic:Subprocess types 93 . Open a process application in the Designer view.Creating a user attribute definition You can associate unique capabilities or qualities with one or more users by creating user attribute definitions. These whitelists are included in the 00static. Open the Process Designer desktop editor. When a user creates a new user attribute definition in a process application. which can be time consuming. You can use defined attributes when you create teams that are based on a user attribute rule. Click the plus sign next to Data and select User Attribute Definition from the list of components.xml file. See Deactivating dynamic group updates.xml file.Can only see attributes of themselves and other users listed as public-attribute . 94 .server/user-attributes/rest-authorization/public-attribute .server/user-attributes/rest-authorization/self-managable-attribute When accessed using a REST API. For more information. 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. About this task This procedure triggers dynamic group creation. Before you begin To perform this task. see Deprecated: Defining Team rules.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. you must be in the IBM® Process Designer desktop editor. provide a unique name for the attribute.xml file and can be overwritten by users in the 100custom. 3. . and click Finish. users that are not assigned privileges in the ACTION_MANAGE_ANY_USERATTRIBUTE action policy: . 2.<server> <user-attributes merge="mergeChildren"> <rest-authorization merge="mergeChildren"> <self-managable-attribute merge="append">CustomAttribute</self-managable-attribute> </rest-authorization> </user-attributes> </server> To create a user attribute definition: Procedure 1. In the New User Attribute Definition window. You can configure IBM Business Process Manager to deactivate these triggers. 4. Parent topic:Creating a business process definition (BPD) 95 . Select the source from the list. 6. Source If you select Any Allowed. Source Obtain possible values from. Description Displays the name that you provided in step 2. or List.. Supply the following requested information about the user attribute definition: Table 1. The source is IBM Business Process Manager... Specifies that the possible values for the attribute are limited only by its business object type. Click Save on the main toolbar. (Optional) Provides a description of the attribute in this field.. The choice that you make determines the information that is required. The default type is String. Click New if you want to define a new business object. Specifies the business object type.IBM Process Designer saves the user attribute definition. Specifies the sources of other possible values for the user attribute. Click Select to specify a different type.5. Input required for the user attribute definition Dialog area Common Field or link Name Documentation Type Business Object Obtain current value from.. Enter each possible value in the Value field and click Add. Specifies the source of the current value.. Any Allowed. 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... and you can use the attribute when creating teams. If you select List. Duplicate names and other naming violations If IBM® Business Process Manager Designer detects issues.Problems with parameter mappings . You can click the category to display a list of issues. and then click the Validation Errors tab to list each error for the selected item. The Designer in Process Designer includes validation functions that alert you to issues in your process applications and toolkits. such as missing implementations for activities .Broken references. Double-click an item in the list to open the item.Validating processes Use validation functions to refine process definitions as you build them. Validation provides feedback about the following types of issues: . the Validation errors category in the library displays the number of errors detected. Parent topic:Creating a business process definition (BPD) 96 . Available task types Task type User Task Description User tasks must be completed by process participants and are associated with Human services by default. 97 . Process Designer automatically creates the required user implementation that you need when you drag process components onto a diagram. In this way. When you drag an activity from the palette to a participant lane in a BPD diagram. When you drag a Human service from the library to a BPD diagram. as described in Implementing activities in a BPD. IBM BPM supports the following task types: Table 1. such as an Integration or Advanced Integration service. Process Designer automatically creates an activity with a User task with the Default Human service selected. You can also choose User Task and an associated service for an activity implementation.Task types Learn more about the task types that are available when modeling with IBM® Process Designer. For cases where you want a user to start the service but no additional user involvement is required. Process Designer automatically creates an activity with a User task with the Human service selected. you can also choose a user task type and associate a service with it. Integration service. regardless of whether the service is dragged to a system lane or to a participant lane. Note: Simple and multi-instance loop properties can be defined for all task types. Process Designer automatically creates the System implementation that you need when you drag process components onto a diagram. 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. or Advanced Integration service from the library to a BPD diagram. as described in Implementing activities in a BPD. Process Designer automatically creates an activity with a System task type. For more information.Note: Decision tasks in IBM BPM are equivalent to BPMN 2. Parent topic:Creating a business process definition (BPD) 98 . Decision tasks are useful when you want a decision or condition in a business rule to determine which process implementation is started. see Creating loops for a BPD activity.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. A script uses JavaScript to access and manipulate data. System tasks that you place in a non-system lane are also run by the system. When you drag a Decision service from the library to a BPD diagram. as described in Implementing activities in a BPD. In this way. When you drag an Ajax service. You can also choose System Task and an associated service for an activity implementation. You can also choose Decision Task and an associated Decision service for an activity implementation. Process Designer automatically creates an activity with a Decision task.0 Business Rule Tasks. General System service. 99 . Attention: A process instance user interface must be implemented as a client-side human service.The Default user interface that overrides the user interface that is provided by IBM BPM.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 copy this template and modify it to create your custom UI. You can create a client-side human service and specify it as the user interface. which returns an error if the instance is not found. Optionally. For more information. 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.displays the values of the variables that are passed into the client-side human service. 2. Under Details UI.Data section . select the interface that you want to create (Default or Instance Owners). 1. Any user that has permission to see the process instance in Process Portal will see this interface.Default Instance Details Template . first create a client-side human service. 100 . see Instance Details UI Service template.Creating user interfaces for a BPD Create customized user interfaces that a user sees for the process instance in Process Portal. Select a client-side human service. you can also create your own user interface that is customized for instance owners. The template contains the following coaches: . If you do not specify a client-side human service here. Switch to the Views page. then create your customized interface by modifying the generated service and adding a coach.View Instance Details coach. which contains the following coach controls: . . 4. . the user interface that is provided by IBM BPM is used.displays the instance details in Process Portal . You cannot implement it as a heritage human service.Show error. Open the BPD for which you want to create the user interface. These are the process instance user interfaces that you can create: . called Instance Details UI Services Template. or create a new one. Procedure To create a process instance user interface. IBM BPM provides a template in the Dashboards toolkit. You can create a client-side human service and specify it as the user interface for the instance owners. About this task IBM® Business Process Manager provides a user interface for your instances in Process Portal. 3. Parent topic:Creating a business process definition (BPD) 101 . Process Portal opens in your default browser showing the process instance user interface.Note: If you copied the template in step 4. Switch to the Inspector when prompted.5. C. Open the client-side human service. remove the defensive logic that shows an error when the instance ID is null. and click Run to test the client-side human service and the coach. To automatically map input properties with process variables. In the Inspector. enter data. 7. 6. click the auto-map icon . Open the BPD and click Run Process in the toolbar. You can view the user interface. Map the process variables to the client-side human service variables. and interact with the process. select the process instance and click the Runs the Details UI for the selected BPD Instance in the toolbar. B. To test the interaction between the user interface and the process: A. . The type of service that you choose to create depends upon the requirements of the activity. If an activity requires that call center personnel enter data about customer requests.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. you can create a human service with a coach. or user interfaces. Within a client-side human service. clientside scripts.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. . Process Designer implements the associated activity or action.Service components Learn about the tools and components available when building services in IBM Process Designer. When a BPD starts and the tasks within it are invoked. if an activity requires integration with an external system. when a certain condition evaluates to true. . you can create an integration service. services perform the required functions. you can use coaches. . and so forth.Building a General System service Use General System services when you want to orchestrate other background services. or perform some 102 . .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. .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. manipulate variable data. For example.Building services Use services to implement the activities in a business process definition (BPD). such as a database.Case management functions are only available if you have IBM BPM Advanced with the Basic Case Management feature installed. . For example.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). generate HTML for a Coach.Building an integration service Build an integration service when you want a flow to interact with an external system. such as for auto-completion in text fields. dashboards. and services to create a service flow that is run entirely in a web browser. .Service types Learn about the types of services available in IBM BPM and when to use each type. for default selection values in selection lists. . Parent topic:Modeling processes 103 .other actions that do not require any integrations or business rules. heritage coaches. The type of service that you choose to create depends upon the requirements of the activity. you can create an integration service. The following table describes the types of services available in IBM BPM: Table 1.. 104 See. For example. you can create a client-side human service with a coach.Service types Learn about the types of services available in IBM® BPM and when to use each type. A heritage human service is the only type of service that can call other heritage human services. Heritage human services run on the server and supply user interfaces to a web browser. if an activity requires integration with an external system. and postpones. Heritage human services are authored in the Process Designer desktop editor. If an activity requires that call center personnel enter data about customer requests. Building a heritage human serviceDifference between client-side human services and heritage human services . and can contain coaches. 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.. such as a database. services. client-side scripts. and can contain coaches. Client-side human services are authored in the Process Designer web editor. but an Ajax service can call other nested services. You cannot call an Ajax service from other types of services. An Ajax service can pull data dynamically from a connected data source. 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. 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. 105 . a dashboard.Client-side human service Use a client-side human Building a client-side service to implement an human service interactive task. Client-side human services run within a web browser and can call the server for data when needed. such as a database. when a certain condition evaluates to true. IBM BPM implements the JavaScript expression that you provide. You can call an integration service from any other type of service and an Integration service can call other nested services. For example. Use an integration service when you want to integrate with an external system. Decision services cannot include Java™ or Web Service integrations directly. 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 . You can call a decision service from any other type of service and a decision service can call other nested services. An integration service is the only type of service that can contain a Java or Web Service integration.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. General system services cannot include Java or Web Service integrations directly.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. Parent topic:Building services Related information: Examples of building services with heritage coaches 107 . you can use a general system service. You can call a general system service from any other type of service and a general system service can call other nested services. or XSLT) directly to a service variable.Decision service . XML. Use to model a point in the process execution where only one of several paths can be followed. depending on a condition. Not all tools and components are available for each type of service. . the following tools and components are available from the palette. The Server Script component is useful for parsing through variables and executing programmatic commands. For services that contain multiple paths. Use when you want to write JavaScript to run on the Process Server in the service context. Use to end service execution. This eliminates the need to store large blocks of text in default values for variables. Enables you to connect service components to establish the order in which the steps in the service occur.Heritage human service . Use to add information about the overall service or each step in the service to the diagram. HTML.Integration service . Use to bind blocks of formatted text (for example. Note: An end event is automatically included each time you create a service.All service types .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. each path requires its own end event. Adding notes helps other developers understand your design. 108 .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. Use to purposely throw an error and end processing. the Send Alert component was used to send alerts to an IBM Process Portal user. This component enables you to supply a WSDL URI and then use any of the available services. Use to indicate a point in a service at which you want IBM Business Process Manager to capture the runtime data for reporting purposes. Integration service The following tools and components are available from the palette for Integration services only:Table 2. 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. 109 . alerts can be retrieved only with the TWSearch JavaScript API by querying on tasks with the status of Alert. Note: Human and Ajax services cannot be nested. for example. Use to send task-related alerts (deprecated). Tools and components available from the palette for Integration services only Component icon Description Use to run an external web service. You might. Starting in IBM Business Process Manager V8. Nested services are often used in multiple process applications and likely reside in a toolkit. Use to incorporate other services in your current service. integration with outside systems. In prior releases. or data manipulation. repeatable functions such as exception handling routines. Nested services are generally defined to perform specific. For more information about tracking data. Use to listen for errors from the service component to which it is attached. Note: You must use a nested service to invoke an Advanced Integration service. see Enabling processes for tracking and reporting. see Building coaches. 110 . Tools and components available from the palette for Decision services only Component icon Description Use to build conditions for your Decision services. The coach tool is shared with the client-side human services. or other aspects of a task. Use to halt processing without changing the status of a task. Use to include decision services available on an ILOG JRules Rule Execution Server. You can use the methods to complete tasks like reading or writing files or sending SMTP mail. For more information. status. Use to change the priority. This component is used for heritage human services only. 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. For more information. This component is used for heritage human services only.Table 3. Use to implement the interfaces for your heritage human services so that users can participate in a business process. Use to integrate with an IBM Enterprise Content Management system.Use to call methods from a Java class. due date. see Tools available from the palette for client-side human services. Decision service The following tools and components are available from the palette for Decision services only:Table 4. see Building heritage coaches. Heritage human service The following tools and components are available from the palette for heritage human services. Parent topic:Building services Related information: Tools available from the palette for client-side human services 111 .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. Consider encapsulating your rules in a single-function Decision service.Decision Table . IBM® Process Designer supports business rule authoring tasks as performed by business analysts and business users who are rule designers rather than programmers. Business rules formalize a business policy into a series of "if-then" statements. When building a Decision service. which allows the service to be available to any other part of the process application that needs the same rule logic. Process Designer implements the associated activity or action. business rules are included in a business process definition (BPD) by adding a Decision service to the process. When a rule evaluates to true. if an employee holds the position of Director and submits a meal expense for more than $250. You can use this rule component to connect to and implement rule applications that are available on a JRules Rule Execution Server. to route the process sequence flow into a specific approval activity. a natural language technology. . 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.BAL Rule .JRules Decision Service .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. follow these guidelines: . Each row in the rule table represents a Boolean condition that evaluates to true or false at run time.You can use the rule editor in this component to author business rules using Business Action Language (BAL).IBM Business Process Manager integrates with IBM WebSphere ILOG JRules using the JRules Decision Service component. when a certain condition evaluates to true. There are three types of components: . . For example. Add a Decision service to a Process Application when the actions that should take place in your process depend upon one or more conditions.The Decision Table component contains a rule table. 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. In Process Designer. such as approvalRequired.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. . 112 . This rule syntax is called Business Action Language (BAL). the JavaScript expression that you provide as the rule action is started. For example. which is a declarative language that relates business concepts to business data and actions. Business rule designers can express business logic using rule syntax that resembles natural human language. then you can create a rule and set a variable in the rule. A Decision service contains one or more components. 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. Use a Decision service when you want a decision or condition to determine which process implementation is invoked.Implementing an activity using a Decision service You can implement an activity using a Decision service. such as a BAL Rule component. . You can migrate the rules that you created in Process Designer to a business rules management system (BRMS) such as IBM WebSphere® ILOG® JRules. output.Scenario: Creating a Decision service in a Personalized Notification process This scenario shows you how to create. when a certain condition evaluates to true. . If an error or exception occurs within a rule. IBM Process Designer implements the associated activity or action. and private variables that are declared for that service. implement and manage business rules in Process Designer. instead of JavaScript. and the rules are easier for people to read and understand. . . 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. the variable appear in the Content Assist menu in the rule editor. You can also attach a Decision service to a decision gateway.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. and then continue to use the rules in a business process definition. and you can debug the specific rule component or rule that caused the error.Testing a Decision service When you have finished creating a Decision service and authoring rules in a rule component. . you will see messages about the error during testing. . For example. . you can test the Decision service to determine if the rules are being applied as you intended. depending on a condition.Adding and modifying Decision service variables Each IBM Business Process Manager Decision service has a set of input.The following topics describe how to author.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). to author rules means that no programming expertise is required to create business rules. . For example.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 . . Using natural language. The business terms and phrases that you define as variables are available for you to use when you are writing rules. configure and test Business Action Language (BAL) rules in a Decision service.Adding a Decision service to a process You can add a Decision service to a business process definition (BPD). work on in IBM WebSphere ILOG JRules Rule Studio. 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. is available in the IBM WebSphere ILOG JRules InfoCenter.BAL reference A reference guide to the Business Action Language (BAL). which is used to author rules in IBM Business Process Manager. . Parent topic:Building services 114 .Adding a JRules Decision Service component to a service When building a Decision service in Process Designer. . .Decision service limitations Some functions and variables are not supported in a Decision service. configure and test Business Action Language (BAL) rules in a Decision service. B. complete these steps: 1. Before you begin To perform this task. 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. In the Library panel on the left side of the Process Designer window. then click Finish. The process includes a Decision service with BAL rules to decide whether a notification is sent to the customer. or the "Send notification" decision path. A. Open the Process Designer desktop editor. In the Create New window. Procedure To add a Decision service to the Personalized Notification process. 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. The Decision service defines the conditions that must evaluate to true in order for the notification step to be triggered. In the New Decision Service window. enter NotificationRulesService as the Decision service name. 3. 2. 115 . click Decision Service. Click the plus sign next to Decisions to add a new Decision service. move the mouse cursor over the Decisions item in the list of library items for the process application. Create a new Decision service called NotificationRulesService. Open a process application that contains a business process definition (BPD). D.Scenario: Creating a Decision service in a Personalized Notification process This scenario shows you how to create. you must be in the IBM® Process Designer desktop editor. you can attach the NotificationRulesService to the Send Alert decision gateway. Using the following steps. C. The rules in the Decision service control whether the sequence flow coming out of the gateway follows the "No notification" decision path. Click Save. In the Create New window. select Complex Structure Type as the Definition Type. Click the plus sign next to the Data library item.You can find more information about adding a Decision service in the related topic "Adding a Decision service to a process. In the New Business Object window. B. 116 . A. D." 5. enter CheckingAccount as the name for the business object. add the CustomerName parameter with the variable type set to String. 2. 2. Add parameters to the CheckingAccount business object. Click Save. In the Properties tab. click Add. the Balance parameter with the variable type set to Decimal. Create a business object called CheckingAccount that contains parameters such as CustomerName. Click BAL Rule in the component palette and drag the BAL Rule component icon from the palette to the service diagram. enter AlertRules ad the name for the new BAL Rule component. B. Balance and Payments. click Business Object. or use the Ctrl+S keyboard shortcut to save the Decision service. C. Add a business object from the Process Designer library panel. You can find more information about adding a BAL rule component in the related topic "Adding a BAL Rule component to a service. 1. D. In the Behavior section of the Business Object panel. and the PastPayment parameter with the variable type set to Payment. then click Finish. Make sure that you are editing the NotificationRulesService Decision service. 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. 3. In the Parameters section of the Business Object panel." 4. Add a BAL Rule component called AlertRules to the NotificationRulesService Decision service. A. or use the Ctrl+S keyboard shortcut to save the Decision service. 1. 4. In the Parameter Properties section. C. enter notificationOut as the name for the output variable. including the notification message. A. Define which of the parameters are used as input variables to the Decision service. or use the Ctrl+S keyboard shortcut to save the Decision service. 3. Click the plus sign next to notificationOut in the Variables list to confirm that message is included in the list. such as CustomerName. 2. Balance and PastPayment. notificationOut. Click Save. enter accountIn as the name for the input variable.You can find more information about creating a business object in the related topic "Adding variable types and business objects to a Decision service. C. Make sure you are editing the NotificationRulesService Decision service. D. Click the plus sign next to accountIn in the Variables list to confirm that CustomerName." 6. In the Details section. Click the Variables tab. 2. Click Add Input to add the input variables: 1. In the Details section. Click Select next to Variable type and click CheckingAccount in the list. E. and which parameters are output variables from the Decision service. 117 . B. Click Select next to Variable type and click Notification in the list. 3. Balance and PastPayment are included in the list. Click Add Output to add the output variable. 1. The second part of 118 . C. Click the condition placeholder. next to if. . If the list closes before you can select a condition statement.notificationOut .You can find more information about defining Decision service variables in the related topic "Adding and modifying Decision service variables. Add the following condition statements by doubleclicking on each as it appears in the list.set the message of . D. press Shift+Spacebar to reopen the Content Assist menu. A. Use the BAL Rule editor to create rules in the AlertRules BAL Rule component. 1. Type the notification message. the edit cursor appears between two double quotation marks.accountIn The first part of the rule (if) looks like this:if the amount of paymentIn is more than the balance of accountIn E.if the amount of . Payment takes account overdrawn between the double quotation marks.to ." 7. By default.paymentIn . B. the rule editor opens with an empty BAL rule window.the balance of .is more than . with one condition (if) and one action (then).string When you double-click to select string. Click the Decisions tab. Click the action placeholder next to then and add the following condition statements. then click to select the AlertRules BAL Rule component. to use the Content Assist menu to complete the condition. Click inside the rule window to begin creating a new rule from the template. The rule window contains a basic template for a simple rule. . Make sure you are editing the NotificationRulesService Decision service. Click the Diagram tab. Click Implementation in the Properties tab. Click Save. G. Attach the NotificationRulesService Decision service to the Send Alert decision gateway. or use the Ctrl+S keyboard shortcut to save the Decision service." 9. Click the Properties tab. A. click Select. click the Send Alert decision gateway icon to select the decision gateway. Click the plus sign in the upper right corner of the BAL rule editor panel. Click Decision. 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 . C. In the business process definition diagram. You can find more information about using the BAL Rule editor in the related topic "Creating a rule using the rule editor. Click to select the NotificationRulesService Decision service. In the Decision Service section. add a variable statement to each decision to control the output of the decision gateway. Under the Decisions heading. B. Add a second rule editor window. F.the rule (then) looks like this:then set the message of notificationOut to "Payment takes account overdrawn". F. and attaching a Decision service to a gateway. D. You can find more information about decisions in the implementation of a gateway. E. 119 . Make sure you are editing the NotificationRulesService Decision service. in the related topic "Attaching a Decision service to a decision gateway." 8. then set the message of notificationOut to the message of notificationOut + "\n" + "Payment to new payee: " + the payee of paymentIn . Test the Decision service and the BAL rules that you created and attached to the decision gateway. G. you can export the rules into a project file and import them into IBM WebSphere ILOG JRules. F. then you have completed the scenario procedures. When Process Designer prompts you to change to the Inspector interface. click the Debug icon in the banner above the rule editor windows. refer to the related topic "Exporting. 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. configuring and testing the AlertRules BAL rules in the NotificationRulesService Decision service. and identify any errors that might have occurred. For more information about using the Debug service and the Inspector window to identify and fix Decision service problems. click Save. C. If you make any changes to resolve errors in the Decision service or the BAL rules. B. or use the Ctrl+S keyboard shortcut to save the Decision service. Make sure that you are editing the NotificationRulesService Decision service and the AlertRules BAL Rule component. G. The Inspector clearly identifies any errors in the Execution State panel. The Debug service browser window captures error and exception messages. For more information. click to select the Send Alert decision gateway." H. refer to the related topic "Debugging a Decision service. Set a breakpoint for the gateway. The prompt to switch to the Inspector perspective might be covered up by the Debug window. Click Step in the Debug window to run the Decision service one step at a time. migrating and connecting BAL rules to a rule server. In the AlertRules BAL Rule component panel. E.A. and links directly to the source of the problem." 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 . The Inspector also tells you where the error happened. D. In the NotificationRulesService Decision service. What to do next When you have finished creating. If you want to refine or share the rules that you create in Process Designer. click Yes. The IBM BPM Debug Service opens in a new browser window. 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 . 4. 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 service to a process You can add a Decision service to a business process definition (BPD). then click Finish. when a certain condition evaluates to true. see Managing access to the Process Center repository.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. See Declaring and passing variables for more information. you must have access to a process application or toolkit in the Process Center repository. C.Adding a BAL Rule component to a service . Drag a rule component. 2. A. Open the Process Designer desktop editor. Be sure to adjust the input and output variables as required for each implementation. Use a Decision service when you want a decision or condition to determine which process implementation is invoked. JRules Decision Service or Decision Table component. B. Create a new Decision service. click Decision Service. In the Create New window. To create services. D. For example. In the New Decision Service window. follow the additional steps in the following related topics to configure the components in the Decision service: . Open a process application that contains a BPD. Process Designer displays the diagram of the service with the default Start Event and End Event components. from the component palette to the Decision service diagram. IBM® Process Designer implements the associated activity or action. enter a name for the new Decision service. Before you begin To perform this task. 3. such as a BAL Rule.Adding a JRules Decision Service component to a service . Depending on which component or components you added to the service diagram. Access to process applications and toolkits is controlled by users who have administrative rights to the repository. 5. For more information. Click the plus sign next to Decisions to add a new Decision service. you must be in the IBM Process Designer desktop editor. Procedure 1. Adding a Decision Table component to a service 123 . 5. 7. Parent topic:Building a Decision service 124 . complete the following steps: 1. 6. Before you begin To perform this task. click the New button to create it. Click the activity in the diagram to select the activity. you must be in the IBM® Process Designer desktop editor.Implementing an activity using a Decision service You can implement an activity using a Decision service. If the service does not yet exist. Open a process application that contains a business process definition (BPD). 2. Open the Process Designer desktop editor. Procedure To select a Decision service as the implementation for an activity. 4. 3. Open the BPD diagram that contains that activity that you want to implement using a Decision service. Click the Implementation option in the properties. Click the Select button to choose the Decision service that you want from the library. Click the drop-down list and select Decision Task from the available options. If there are multiple decisions in the Implementation properties for the gateway. click Select. When developing processes in IBM Business Process Manager. If no decisions evaluate to true. Click New next to the Service field. To select an input variable statement. click the decision gateway icon to select the decision gateway where you want to attach the Decision service. click the auto-map icon . You can remove an attached Decision service from a decision gateway. based on the result of the rules in the rule component. Click the delete icon (X) next to the Decision service name. you must be in the IBM® Process Designer desktop editor. About this task When you attach a Decision service to a decision gateway. The Inputs section contains a variable condition statement field that controls the behavior of the gateway. 2. The Inputs section includes an auto-map function. 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. 5. complete the following steps: 1. Open the Process Designer desktop editor. 9." 125 . Click Decision. In the BPD diagram. You can also attach a Decision service to a decision gateway. If you decide not to use an existing Decision service. 6. B. 7. Select the Decision service you want to attach to the gateway from the list of available services. 4. Click the Properties tab. To create a mapping between the variables used in the Decision service and the variables that are used in the main business process definition. depending on a condition. the decisions are evaluated from top to bottom and the path for the first decision that evaluates to true is followed. Before you begin To perform this task.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. you can create a new service. 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. the default path is followed. 8. Procedure To attach a Decision service to a decision gateway. Open a process application that contains a business process definition (BPD). A. 3. In the Decision Service section. refer to the related topic "Mapping input and output data for an activity. click the variable icon to display a list of available variables. You can change the position of a decision. which is followed if none of the decisions evaluate to true. then the decisions are No Notification (the process ends with no message sent). which is to send a message. because the rules in the decision service have determined that no notification message is required. for example. The last decision is the default condition sequence line. 11. Click the variable icon to display a list of available output variables that are defined in the Decision service. no message would be sent. Another possibility might be that the customer had an invalid email address. The message sent as output could be in quotation marks.notification. you must also specify a comparison function and a value for each decision.local. by using the arrows you could move the bottom position up to the top position and the code would be displayed. Under a certain set of conditions. or Send Notification. This output would be determined by the logic of the decision service. For example. which would contain the order number for something the customer had ordered. For example. The example decisions are illustrated in the following figure: In this screen capture. no text will be sent as indicated by the quotation marks with no text inside (""). "Your order is confirmed. 12.message in the top position is set to no message as output. if the purpose of the decision gateway is to determine whether a notification message is sent to a customer or not. In this example. The text field for each decision shows the JavaScript object that represents the variable condition. add an output variable statement. so no message would be sent. Under the Decisions heading. For each decision above the last (default) decision. the input variable tw. however. Click the down arrow or the up arrow next to a decision to move it down or up in the decision list. 10. Parent topic:Building a Decision service Related information: Mapping input and output data for an activity or step 126 ." or the message sent as output might be in an another variable such as orderConfirmationNumber. The variable name is displayed to the right of the Inputs field. if the decision service checked a database and found that the customer no longer existed it would not send a message. The value of the Send Notification decision is determined by variables that are defined in the rules. To enable the process to process the decision and choose the correct output sequence line for the decision gateway.The text field under the Inputs heading shows the JavaScript object that represents the variable. Send Notification is the default decision. This is the default output.The input variable and its output in the bottom position are hidden in this screen capture. that is. Click Implementation in the Properties tab. The value of the No Notification decision is null. 13. add a variable statement to each decision to control the output of the decision gateway. 127 . and the rules are easier for people to read and understand. Restriction: The following variable types cannot be used with BAL rules in Decision services: . Using natural language.SQLResultSetColumn .NameValuePair .XMLNodeList Procedure 1. About this task The following steps describe how to add a BAL Rule component to a sample Decision service.TWHolidaySchedule .SQLResultSetRow .SQLResult .Record .TaskListData .SQLStatement .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. In the diagram of the new Decision service.TaskListSortBySelectionType .Map . instead of JavaScript.TWTimePeriod . The sample service is a singlefunction Rule that can be called from any other service.IndexedMap . to author rules means that no programming expertise is required to create business rules.SLAViolationRecord .XMLDocument .SQLParameter .TaskListProperties .SQLDatabaseType . The purpose of the sample service is to determine whether approval is required for certain employee expenses.TWWorkSchedule .TWTimeSchedule .ConditionalActivity .XMLElement .TaskListFilterProperties . click BAL Rule in the component palette and drag the BAL Rule component icon from the palette to the service 128 . 2. 3. Open the process application in the Designer view. Create a Decision service.TaskListItem . A. The Boolean variable type is included in the IBM® BPM System Data toolkit.Business rule parts and structure Business rules. What to do next Create a rule that is implemented for this Decision service. Parent topic:Building a Decision service Related information: 129 . express business policy statements using a predefined business vocabulary that can be interpreted by a computer. 6. 10.diagram. The System Data toolkit is included in each process application by default.Copying and pasting content in the rule editor You can copy content from a rule to the system clipboard. Click Add Private. B. 5. such as action rules or decision tables. 7. 4. For this sample Decision service. 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. . To access the wizard.Troubleshooting BAL rule editor errors The Business Action Language (BAL) rule editor highlights errors with red underline in the editing window. Click Select next to Variable Type and select the type from the list. add the private variable. 8. . Replace Untitled1 in the Name field with approvalRequired .Creating rules using the rule editor You can create rules using the Business Action Language (BAL) rule editor. right-click an activity icon in a process diagram and select Activity Wizard from the list of options.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. Replace Untitled1 in the Name field with request . . You should use the Activity Wizard when you start with an existing activity and want to quickly create a service to implement the activity. Click Add Private to add a private variable to the Decision service. or paste content written outside the rule editor into the editor window. . If you use the Activity Wizard to create a Decision service. In the Properties tab. 9. such as ExpenseApproval. . Click Select next to Variable Type and select the Boolean type from the list. Rules authored in the Business Action Language (BAL) are also easily readable by humans. you can choose existing variables to add as input and output. request.Defining variables in the rule editor Variables are defined in the definitions part of a business rule. 11. Click the Variables tab. enter a name for the new BAL Rule component. Click the Decisions tab to open the rules editor. Refer to the related topic "Authoring rules using the BAL rule editor." . Declaring variables for a BPD or a service in Process Designer 130 . next to if. the rule editor opens with an empty BAL rule window.If the list of conditions is long. add rule parts. you can use the Tree Completer menu instead of the Content Assist menu to select the condition statement. to use the Content Assist menu to complete the condition. start typing the condition name. press Ctrl+Shift+Spacebar to open the Tree Completer menu. if part 3. By default. 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. else part (optional) For more information about the parts and structure of a business rule. . statements. then part 4. parts. Double-click a condition statement in the menu to add that condition to the rule. values. The parts must be defined in the following order: 1. Click the condition placeholder. 3. Click the Decisions tab to open the rule editor." The following steps describe how to author a rule using the rule editor." 2. definitions part (optional) 2. Procedure 1. as shown in the following diagram: 131 . . 4. A. 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. While you are creating or editing rules. and replace placeholders with variables and values. the editor highlights errors to help you identify and resolve problems in your rules. Use the completion menu in the editor to insert or edit constants.Creating rules using the rule editor You can create rules using the Business Action Language (BAL) rule editor. A business rule consists of some or all of the following parts. The purpose of the sample service created in the procedure steps is to determine whether approval is required for certain employee expenses. Click inside the rule window to begin creating a new rule from the template.If you know the name of the condition you want to insert. with one condition (if) and one action ( then). The rule window contains a basic template for a simple rule. The Tree Completer shows all the conditions that match the name as you type. and fragments. The rule is implemented in a BAL Rule component as part of a sample Decision service. About this task You can use the BAL rule editor to build rules. refer to the related topic "Business rule parts and structure. With the edit cursor on the <condition> placeholder. The sample service is a single-function rule that can be called from any other service. or fragments of rule statements. you can change the order of the rules. In a BAL Rule component that contains multiple rules. Each window contains the simple rule template." 5. or click the Save icon in the Process Designer action bar. To add additional rules to the BAL Rule component. click the exit icon (X) next to the Decision service name. then press Ctrl+Spacebar to activate the Content Assist menu. "Inserting a term or a phrase. click before the if condition section. 8. 6. next to then. a rule editor window is opened. refer to the related topic in the IBM WebSphere ILOG JRules InfoCenter. to select from the menu of possible actions. Double-click an action statement in the menu to add that action to the rule. click Ctrl+S. 7. click to place the editor cursor above or below the existing rule content. Each time you click the plus symbol. For example. 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 . click below the then section of the rule. To exit the rule editor. To create an else rule part. To save all the rules in the BAL Rule component while you are authoring. Click the up arrow beside the editing window to move the rule up one place in the rule order. to create a definition rule part. click the plus symbol at the top of the rule editor window.B. 9. The Content Assist box displays a list of valid rule parts. then press Ctrl+Spacebar to open the Content Assist menu and select definitions. For more information about using the menu to select actions. The rule editor saves the rules periodically as you are authoring. Click the action placeholder. To add additional rule parts to the rule. Click the down arrow to move the rule down one place in the rule order. definitions . Conditions The condition part of a rule specifies under what conditions the actions in the action part of the rule will be carried out. customer). "Understanding your rules -. The parts must be defined in the following order: 1." A related link is provided. Variables help you identify and then reference an occurrence of a business term by a convenient name. definitions part 2. if (conditions) part 3. such as action rules or decision tables. express business policy statements using a predefined business vocabulary that can be interpreted by a computer.Definitions. For more information about complex versions of the definition part. Rules authored in the Business Action Language (BAL) are also easily readable by humans. or adding a where clause to a definition to apply further restrictions on the variables.then . by declaring a variable called minimum_score in the example rule. For example. . Define a variable by giving it a name of your choice and then setting a value for the variable. it becomes available in all the parts of the current rule. Conditions are represented in the rule editor by 133 . This value can be a number (or an arithmetic expression whose result is a number).the credit score of the borrower is less than minimum_score . The variable is valid only in the rule in which it is defined.definitions .if .Business rule parts and structure Business rules. then (actions) part 4. such as multiple occurrences of a value. Use variables to make your business rules less ambiguous and easier to understand. refer to the related section in the WebSphere ILOG JRules InfoCenter.set minimum_score to 200.set minimum_score to 200. The simplest use of definitions is to define a constant value that you can use throughout your rule. text. 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. you make the rule easier to understand: . This is a very basic illustration of the definitions part of a rule. 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: . For example. or a predefined business term that already exists in your rule (for example.refuse the loan with the message "Credit score below" + minimum_score. Once you have set a variable. The condition part of a rule can be made up of one or more condition statements. and issue a message "Credit score below 200.Conditions" in the WebSphere ILOG JRules InfoCenter.the value of the shopping cart is more than $100 . 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. The action is carried out if this condition is true. Actions The action part of a rule describes what to do when the conditions of the rule are met.then .then . the action is defined so that when the condition evaluates to true.set applicant to a customer." . You can use an else rule part in combination with variables in the definitions part to control the rule action more precisely. the condition is defined so that when the credit score of the borrower is below the minimum value. For more information about actions.Actions" in the WebSphere ILOG JRules InfoCenter. . This sample rule shows this application for the else part: .if .definitions .if . . The word then signals the beginning of the action part of the rule.else . 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. For more information about conditions.the text (or number) that appears after if.In the example rule. 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 .the credit score of the borrower is less than minimum_score This is a simple condition that is either true or false. refer to the section "Understanding your rules -.refuse the loan with the message "Credit score below" + minimum_score.In the example rule. Actions are represented in the rule editor by the text that appears after then and else. The else part of a rule is an optional block of actions that specify what to do when the conditions are not met. If a rule contains both definitions and a condition part. Optionally.apply a 15% discount . you can include an else part in a rule. This rule applies an extra discount only for customers who qualify for the Gold category. refer to the section "Understanding your rules -. where the category of this customer is Gold. ending at then.apply a 5% discount. then the loan to the customer is refused. then the resulting action is to refuse the loan. 135 . definitions 136 . Type over the placeholder variable name to replace variable1 with the name of your variable. Before you begin Variables are accessible from business rules when you add them to the rule vocabulary. you can use a variable to define a one-to-one relationship between business objects. The content of the Content Assist menu changes to show the default name for new variables. every variable name is associated with a variable type. in. and select a variable type from the menu." 5. and double-click to select set from the Content Assist menu. you must put the phrase between quotation marks. For more information about verbalizing variables. or where.Defining variables in the rule editor Variables are defined in the definitions part of a business rule. and where. For more information. the variable the shopping cart is defined using the one-to-one relationship between two objects: the ShoppingCart and the Customer: . refer to the related topic "Variable types. If your variable is only one word. 3. Variable names must be unique within a rule. Example To make a rule easier to read. refer to the related topic "Adding and modifying Decision service variables. you can use the variable in all parts of the business rule. although the variable can be used in a all parts of the rule. or the optional building blocks from. complete these steps: 1. which determines what values are legal for the associated variable. press Ctrl+Spacebar. in. After the definitions are specified. Press Ctrl+Spacebar. Double-click in the Content Assist menu to insert the placeholder variable name variable1 in the rule." About this task You can use a variable to identify and then refer to an occurrence of something by a convenient name. When you create a variable in a rule. In the following business rule. the variable is only valid for that rule. The variable definition ends with the closing semicolon. select the closing semicolon. Procedure To define a variable. If your variable is a phrase containing more than one word. variable1. 2. In the definitions part of the rule. To define a variable using the optional building blocks. the Content Assist menu changes to show the closing semicolon. Once a variable is defined. In IBM BPM. the Content Assist menu changes to show the closing semicolon. If you have finished defining the variable. After the variable type is specified. 6. continue by selecting from. quotation marks are not required. Use variables to make your business rules clear and easy to understand. 4. What to do next You must initialize complex variable structures before running the Decision service. If you do not initialize a complex variable or list." Parent topic:Adding a BAL Rule component to a service Related information: Variable types 137 . you may receive runtime errors or notice that the controls to which the variables are bound do not behave as expected.then . . In IBM® BPM. For more information.apply 10% discount. "Initializing complex variables and lists.- set customer to a customer. set the cart to the shopping cart of customer.if .the value of the cart is less than $100 . all complex variables and all lists (arrays) must be initialized before you use them in a BPD or service. refer to the related topic. Copy the content to the clipboard using a keyboard shortcut. From the main product menu. B. C. 2. Make sure that the content you want to paste into the rule has been copied into your system clipboard. or the right-click menu. Parent topic:Adding a BAL Rule component to a service 138 . as described in the following steps: 1. From the main product menu. 3. or the right-click menu. complete the following steps: 1. click Edit > Paste. To select the entire content of the rule. 2. Paste the content to the rule editor window using a keyboard shortcut. Procedure To cut or paste content in the rule editor. To paste content from the system clipboard into a rule. click Edit > Copy. For example. Click to place the edit cursor inside the rule in the location where you want the pasted content to appear. or the product menu. You can copy the contents of an individual rule to the system clipboard. on a Microsoft Windows system. Click to place the edit cursor inside the rule that contains the rule content you want to copy. Right-click in the rule editor window and select Copy from the menu. Highlight the content you want to copy. 3. the copy function shortcut is Ctrl+C. B. on a Microsoft Windows system.Copying and pasting content in the rule editor You can copy content from a rule to the system clipboard. or the product menu. A. Right-click in the rule editor window and select Paste from the menu. as described in the following steps: 1. the paste function shortcut is Ctrl+V. press Ctrl+A. A. Press the copy keyboard shortcut for your system. 2. For example. C. Press the paste keyboard shortcut for your system. or paste content written outside the rule editor into the editor window. complete these steps. click File > Preferences 2. Once the locale is set. if you add new rules to an existing BAL Rule component that was created before you changed the locale. complete the following steps: 1. Click English next to BAL Decision Locale.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. Parent topic:Adding a BAL Rule component to a service 139 . but you can change the locale setting to change the language used in new BAL Rule components. Procedure To change the locale setting. About this task The BAL Rule component language is set to English by default. From the main menu. Click Rules. not the updated locale preference setting. you can create new BAL Rule components using the updated locale. the added rules use the locale setting from the BAL Rule component. then select a language from the menu. Click IBM BPM to display the available options. 4. However. 3. Put your cursor on the error indicator to display the error messages. use the mouse to hover over the highlighted error in the editor. or place your cursor on the error and press Ctrl+1. To see a proposed Quick Fix. click to select the appropriate fix. Click the light bulb icon or move your cursor to the error in the rule. click the light bulb icon next to the error indicator in the rule editor window. Using Quick Fix to identify and fix errors The Eclipse Quick Fix feature is available in the BAL rule editor. Warnings are underlined in yellow. When the error tip window is displayed. click the underlined text in the error to go to the location of the error. 3. 2. and press Ctrl+1 to open the Quick Fix message. Quick Fix messages offer suggestions to help you correct rule errors. To auto-correct an error from the quick fix message: 1.Troubleshooting BAL rule editor errors The Business Action Language (BAL) rule editor highlights errors with red underline in the editing window. Errors are underlined in red. From the list of suggestions. To identify and correct an error in a rule.The messages provide a list of possible corrections from which you can select the appropriate fix. 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. Parent topic:Adding a BAL Rule component to a service 140 . Type in the editing window to correct the error. 141 . Click the Variables tab. 3. 142 . Existing variables are organized into three sections: Input. A service can also include private variables for processing that occurs only within the service. 2. you must be in the IBM Process Designer desktop editor. 4. 5. Before you begin To perform this task. output. The business terms and phrases that you define as variables are available for you to use when you are writing rules. Click the plus sign next to a section to see the variables in that section. or both. Make sure you have selected the Decision service where you want to add or modify variables. complete the following steps: 1. as shown in the following example. For more information about variables in a Decision service. For example. About this task A Decision service might require input or output variables. refer to the related topic "Declaring variables for a service.Adding and modifying Decision service variables Each IBM® Business Process Manager Decision service has a set of input. and private variables that are declared for that service." Procedure To add or modify variables for a Decision service. and Private. Output. Open the Process Designer desktop editor. Open a process application that contains a business process definition (BPD) in the Designer view. the variable appear in the Content Assist menu in the rule editor. 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. . The variable is used for both input and output at the Decision service level. You can add a variable to the Decision service by completing one of the following steps: .6. a variable that is referenced in a rule but is not updated at run time is identified as an IN variable. The following information applies to variables: ." 143 .Click Add Input to add a variable that you can use for input into a rule.The input or output designation for variables might affect the way the Decision service runs. For example. refer to the related topic "Adding variable types and business objects to a Decision service.Exposed Process Variables (EPVs) are managed at the process application level.Variables are mapped to the IN. . output and private variables are all referenced identically in a BAL rule. only one variable is actually created. refer to the related topic "Creating exposed process values." . .Click Add Private to add a variable that applied only to the current Decision service. . OUT or IN-OUT parameter directions automatically.Click Add Output to add a variable that you can use for output from the rule. but the designation is not significant when you are authoring BAL rules because input. 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. depending on how the variable is used in the rule. For more information about parameters.If you create an input and an output variable that have the same name. " . 144 .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 modify or view the properties of an existing variable. refer to the related topic. or define a new variable type. and is available for all business process definitions (BPDs) and services included in the process application. If you do not initialize a variable. In IBM BPM. all private variables must be initialized before you use them in a business process definition or Decision service. "Initializing complex variables and lists. you may receive runtime errors or notice that the controls to which the variable is bound do not behave as expected. or view the Default Value of the variable if a default value has been defined." What to do next You must initialize private variables before running the Decision service. Click to highlight the variable name. For more information about defining a new variable type using the Business Object editor. Click Select to set or modify the current variable type. as shown in the following example: 8. B. then modify the variable properties under the Details section. you can create a custom business object (variable type) for the Decision service. refer to the related topic "Adding variable types and business objects to a Decision service. Select an existing Variable Type. .7. For more information. The variable type becomes part of the data for the process application. A. Click New to define a new variable type. then setting the variable type. Parent topic:Building a Decision service Related information: Adding variable types and business objects to a Decision service Creating exposed process values (EPVs) 145 .Variable types You can define a Decision service variable by first specifying the name of the variable. The variable value can be a simple data type such as a string. or date.. You can also define a complex variable type using a business object that contains parameters. integer. with a few exceptions. when you create a new variable in the Rule editor.XMLDocument . The System Data toolkit includes assets that all IBM BPM projects require. including variable types.SQLResult . 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. For example.XMLNodeList Decision service parameters 146 . The Decision service can use most of the pre-defined variables and variable types. the following list of default variable types is displayed: The following variable types are not supported for Decision service variables: . and select a business object (variable type) to associate with the variable.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.XMLElement . A variable type . which are defined for each business object (variable type) provide a mechanism for exchanging data between a rule component and a process application.Decision service parameters. or output from the Decision service.A direction. For information about setting up Decision service parameters.A business object name . The direction setting is determined automatically based on how the parameter or variable is used in the rule." Parent topic:Adding and modifying Decision service variables Related information: Adding variable types and business objects to a Decision service 147 . You can define Decision service parameters using the following elements: . see the related topic "Adding variable types and business objects to a Decision service. but is not modified or updated when the service is running. any parameter or variable that is referenced in a rule. is identified as an IN variable. For example. which indicates whether a parameter is used as input to a Decision service. or both. Select Simple Type to create a new variable type using an existing type such as String. B. then click Finish. For more information about creating simple variable types. 2. In the New Business Object window.Select Complex Structure Type to create a new complex variable type.To add a variable type while working in the Decision service: A. E. refer to the related topic "Adding process variables to a BPD. and is available for all business process definitions (BPDs) and services included in the process application. Make sure you are working in the Decision service where you want to add the new variable type. 4. Access to process applications and toolkits is controlled by users who have administrative rights to the repository. D. you must be in the IBM Process Designer desktop editor. C. Follow the procedure steps to define the new business object (variable type).To add a business object from the library panel: A. refer to the related topic "Creating custom variable types. . C. click Business Object. type a name for the variable type. In the Behavior section. To create a custom business object (variable type). Open the Process Designer desktop editor. In the Details section. Click the plus sign next to the Data library item. 3. or select the variable where you want to add the new variable type. Follow the procedure steps to define the new business object (variable type)." . B. Decimal.Adding variable types and business objects to a Decision service In IBM® Business Process Manager. Open a process application that contains the Decision service. you must have write access to a process application or toolkit in the Process Center repository. In the New Business Object window."As 148 . Create a new variable. For more information about adding variables. You can add a variable type from the library panel. The variable type becomes part of the data for the process application. F. Before you begin To perform this task. Click the Variables tab. type a name for the variable type. . refer to the related topic "Adding and modifying Decision service variables. you can create a custom business object (variable type) for the Decision service." D. or from the Variables tab while you are working in the Rule service. In the Create New window. then click Finish. You can create a custom variable type by adding parameters and parameter properties to the business object. . click New next to the Variable Type field. For more information about creating complex variable types. Procedure To add a business object (variable type) to a Decision service. complete these steps: 1. or Integer. select a Definition Type from the list. you are adding parameters for a complex structure 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. open the Advanced Properties section and click View XML Schema. 5. 6. click Save in the main toolbar. 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 . To see how the variable parameters are declared in the XML schema. Return to the Decision service editing panel. you can see the resulting changes to the XML schema for the variable type. Refer to the related topic "Initializing complex variables and lists" for more information. When you have entered all the necessary parameters and settings for the variable type. then click Select next to the Variable Type field. The variable type that you added is listed as an available type. For more information. The unsupported variable types are: . You can create rules about complex data that is nested. You can create complicated rules with nested variable structure. integer. If you do not initialize a complex variable or list. Data that is referenced within the text of a rule is not limited to simple data types such as string. nested variables. and contains other. all complex variables and all lists (arrays) must be initialized before you use them in a business process definition or service. the variable paymentIn has the variable type Payment. integer." There are several complex variable types that are not supported when authoring rules in a Decision service. You can also define a complex variable type using a business object that contains parameters.Variable types You can define a Decision service variable by first specifying the name of the variable. or date. For more information about creating complex. hierarchical variable types.Important: You must initialize complex variable structures before running the Decision service. The variable value can be a simple data type such as a string. or date. in the Decision service shown in the following diagram. refer to the related topic "Initializing complex variables and lists. For example. you may receive runtime errors or notice that the controls to which the variables are bound do not behave as expected. 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. or hierarchical. In IBM® BPM.SQLResult 150 . then setting the variable type. see the related topic "Adding process variables to a BPD." 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. and there are multiple line items in the invoice. using Business Action Language (BAL) rule constructs. to open the Record business object included in the System Data toolkit. Predefined variable types Many pre-defined variable types are provided by the IBM BPM System Data toolkit. instead of just a single object. You can use a variable to retrieve a collection (list) of objects of a specific type. or business object.XMLNodeList Collections (lists) of variables You can write rules against collections. 151 . add a list parameter in a complex variable to your rule.XMLDocument . which means that it contains multiple objects of the String. 2. then process this invoice manually). Use a list parameter in a business object when then are numerous objects that your rule must run against. PastPayment is a list parameter. if you are writing a rule about an invoice. complete these steps: 1. To write a rule against the number of line items (if there are 10 or more line items. or lists of variables. You can open a business object in Process Designer and review the Documentation field to learn when and how to use each variable type. Click the indicator next to the Toolkits category to see a list of toolkit dependencies for the current process application. For example. Open a process application in Process Designer. To identify a variable as a collection or list. For example. shown in the following diagram.XMLElement . Decimal and Date variable type. then the invoice is actually a collection of line items.. click to select the Is List option under Parameter Properties. In the complex variable type. These variables are defined as business objects. refer to the related topic "Types of variable definition" in the WebSphere ILOG JRules InfoCenter. 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. For additional information about using variable types in rules. 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 . 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. Click the Data category 5.3. 4. Double-click the Record business object to open it. Click the indicator next to the System Data toolkit to see its contents. 6. . Before you begin To perform this task. showing the step that is currently running in the active process instance. 4. you will see messages about the error during testing. 7. Set a breakpoint in the activity. . The Inspector displays red tokens both in the BPD diagram and the execution step tree. Click the Decision service name to open the rules in the rule editor. you must be in the IBM® Process Designer desktop editor. About this task To test a rule component and the rules it contains. If an error or exception occurs within a rule. and make sure that there are no error messages or exceptions being produced by the Decision service as it runs. When Process Designer prompts you to change to the Inspector interface. Use these testing functions to can examine how the Decision service operates in each step of the process execution.Testing a Decision service When you have finished creating a Decision service and authoring rules in a rule component. Procedure To test a Decision service. 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. complete these steps: 1. 3. Open the Process Designer desktop editor. The 153 . Click the Run service icon in the banner above the rule editor. Open the BPD and click to select the activity or decision gateway in the business process that has the Decision service associated with it. and identify any errors that might have occurred. 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. 2. and you can debug the specific rule component or rule that caused the error. 5.Debugging a Decision service Debug a rule component in a Decision service using the Inspector perspective and the debugging feature in Process Designer. For example. which provides a more detailed inspection than simply stepping through the process. Open a process application that contains a business process definition (BPD) with a Decision service you want to test. which provides a hierarchical view of the execution state. you can test the Decision service to determine if the rules are being applied as you intended. such as a BAL Rule component. click Yes. if you set a breakpoint on an activity that has an associated Decision service.Exception messages in Decision service testing You can review exception messages that result from Decision service testing. you can make sure that the Decision service is producing the data you expect. exceptions provide information that is helpful when you are troubleshooting Decision service execution errors. Parent topic:Building a Decision service 154 . Running the Decision service results in an exception and you need to identify the process step that generates errors. Before you begin To perform this task. For example: . Use these testing functions to can examine how the Decision service operates in each step of the process execution. Click Step in the Debug window to run the Decision service one step at a time. . The IBM BPM Debug Service opens in a new browser window. About this task There are several types of Decision service problems that you can troubleshoot using the Debug Service and the Inspector. as shown in the following diagram: 6. 4.Results from running the Decision service are not what you expected. Make sure that you are working in the Decision service that you want to test and debug.Debugging a Decision service Debug a rule component in a Decision service using the Inspector perspective and the debugging feature in Process Designer. 2. To enable the Debug Service to step through the Decision service execution. Open a process application in the Designer view. Open the Process Designer desktop editor. or click Run to run the complete Decision service. Procedure 1. 5. 155 . Click the Debug icon. which provides a more detailed inspection than simply stepping through the process. set a breakpoint on each activity within the Decision service before running the debug function. you must be in the IBM® Process Designer desktop editor. 3. " 10. The Inspector also tells you where the error happened. some exception messages refer to specific rules by their order number. click Details. To help you locate the rule that produced the error.Note: The prompt to switch to the Inspector perspective might be covered up by the Debug window. Detail message: Object stockQ not found at run time during execution. the Inspector clearly identifies the error in the Execution State panel. such as Rule 1. 8. When Process Designer prompts you to change to the Inspector perspective. To see the complete message. You must make sure that the object has been initialized. Rule 2. The Inspector opens the currently running service in the Services in Debug tab and shows progress through the service. at step BalRule1. using a hierarchical tree in the Execution State panel to show the process step that is running. The Debug service browser window captures error and exception messages. 9. For more information about using the Inspector to debug errors. When you run a Decision service and an exception occurs. Parent topic:Testing a Decision service Related tasks: Resolving errors 156 . as shown in the following example:An error occurred in QuoteLookupRule2 service. see the related topic "Resolving errors. The first few lines of the exception are displayed at the top of the browser window.7. prefixed by the name of the Decision service step. click Yes. and links directly to the source of the problem. Rule 3. Realm.IlrRemoteException at ilog. exception messages include the Decision service name and step name.internal.swt.util.ui.IlrRemoteException: null at call to 'mainRuleflow flow task body' at call to 'execute' ilog.eclipse.java:3622) at org.widgets.sendEvent(Display.java:206) at org.notifyListeners(Widget.java:670) at org.sdk.swt.runEventLoop(Workbench. the following information applies to the exception messages: .widgets. .util.Widget.widgets.java:332) at org.eclipse.sendEvent(EventTable.app.Workbench.res.java:1187) at org.Exceptions in a rule condition cannot be traced to a specific rule.EclipseAppHandle.res.Display.java:1390) at org.rules.session. The exceptions provide information that is helpful when you are troubleshooting Decision service execution errors.sendEvent(Widget.access$4(Workbench. Example of a null exception If a variable value cannot be resolved.util.swt.widgetSelected(ResultsTab.session.sendEvent(Widget.Display.java:1375) at org.widgets.internal. this number helps you track down the location of the error.Workbench.java:149) at com.equinox.res.java:196) 157 .eclipse.java:38) at org.rules. If there are numerous rules in a BAL rules component.eclipse.rules. .eclipse.ui.java:124) at com.res.widgets.Widget.IlrSessionException: An error occurred while the rule session was invoked.samples. When troubleshooting Decision service errors.IlrSessionException: An error occurred while the rule session was invoked.widgets.executeRuleset(IlrRuleService.eclipse.: ilog.java:84) at org.rules.Exception messages in Decision service testing You can review exception messages that result from Decision service testing.swt.run(EclipseAppHandle. or 4.widgets.java:663) at org.java:3776) at org.java:234) at org. .rules.res.Widget.rules.start(Application.ResultsTab$4.documentrules.Exceptions in a rule action can be traced to a specific rule.java:2427) at org.rules.databinding.createAndRunWorkbench(PlatformUI.swt.eclipse.rules.runUI(Workbench.swt.swt.documentrules.eclipse.sdk.eclipse.When a rule component is running.TypedListener.rules.eclipse.IlrRuleServiceException: ilog.session.Workbench$7.eclipse.swt.widgets. as shown in the following example:ilog.ui.eclipse.ibm. such as 1.internal.session.runWithDefault(Realm.runDeferredEvents(Display.java:2629) at org.observable.handleEvent(TypedListener.Display.Workbench. ilog.ui.sendEvent(Widget. 2.EventTable.Widget.java:3277) at org.internal.res.ui.internal.Workbench.Application.The rule name includes a number part that corresponds to the order of the rules in the BAL rules component.eclipse.eclipse.samples.swt.eclipse.java:1367) at org.res.createAndRunWorkbench(Workbench.readAndDispatch(Display.eclipse. this problem results in a null exception. 3.ui.PlatformUI.core.run(Workbench.IlrRemoteException: Ruleset execution error ilog.ibm.eclipse.java:2593) at org.widgets.IlrRuleService.internal. eclipse.invokeFramework(Main.runtime.equinox.adaptor.java:597) at org.java:369) at org.eclipse.res. or notice that the Coach controls to which the variables are bound do not behave as expected.res.EclipseStarter. line 8: error: incompatible values involved in assignments com. refer to the related topic "Uninitialized variable or NullPointerException in a Java snippet.java:574) at org.basicRun(Main.core.reflect.eclipse.invoke(Method.rewrite(RegexExceptionRewriter.IlrRemoteException: Ruleset execution error ilog.at org.0/_bd1ea7af45d14fa9afcea38113db2c35_8cf262cc674e4561bce84c00820bc88e/1.IlrSessionException: An error occurred while the rule session was invoked.eclipse.run(EclipseStarter.core.res.IlrRemoteException Unsupported variable type If you author a rule that uses an unsupported variable type.lombardisoftware.java:310) Uninitialized variable produces a NullPointerException Using an uninitialized variable in a BPEL process can result in various exception errors.Main.java:39) at sun.rules.core.launcher.returnProcessedException(ExceptionHandler. If you do not initialize a private or complex variable or list.adaptor."An error occurred in NotificationRules service.util.launcher. Detail message: Ruleset /b_c54531e1028c40a185bf1115183a3420/1.IlrSessionException: An error occurred while the rule session was invoked.EclipseStarter.runtime.rules.irl'.Method.EclipseAppLauncher.invoke(DelegatingMethodAccessorImpl. you may receive runtime errors.RegexExceptionRewriter.reflect. such as the following example.0 parsing failed 'IRL/rule_1.equinox.util.rules.IlrRemoteException: null at call to 'mainRuleflow flow task body' at call to 'execute' ilog.core. an exception message similar to the following example is displayed:An error occurred in simpleTypeTestService service.core.lombardisoftware.start(EclipseAppLauncher.res. all private or complex variables and all lists (arrays) must be initialized before you use them in a business process definition or Decision service.java:25) at java.Main.eclipse.: ilog.internal. ilog.core.NativeMethodAccessorImpl. at rule 1 in step SimpleTypeRuleStep.java:1407) at org.TeamWorksException.java:1383) Caused by: ilog.lang.java:179) at sun.equinox.java:129) at com.java:110) at org.lombardisoftware.EclipseAppLauncher.DelegatingMethodAccessorImpl.reflect.adaptor.java:79) at org. For more information about errors produced by uninitialized variables. Detail message: Ruleset /b_c54531e1028c40a185bf1115183a3420/1.irl'. at rule 1 in step SimpleTypeRuleStep.runtime.res.asTeamWorksException(TeamWorksException. at rule 1 in step AlertRuleStep.lombardisoftware.session.rules.session.eclipse.TeamWorksException: An error occurred in simpleTypeTestService service.launcher.run(Main.Main.adaptor.ExceptionHandler.java:76) at com.0/_bd1ea7af45d14fa9afcea38113db2c35_8cf262cc674e4561bce84c00820bc88e/1.launcher.core.eclipse.runtime.runApplication(EclipseAppLauncher. line 8: error: incompatible values involved in assignments at com.internal.main(Main. 158 .util.run(EclipseStarter.equinox.Main.NativeMethodAccessorImpl.invoke0(Native Method) at sun.0 parsing failed 'IRL/rule_1.java:619) at org.rules.reflect.core.invoke(NativeMethodAccessorImpl.eclipse. In IBM® BPM. java:417) at com.HttpServlet.lombardisoftware.java:831) Parent topic:Testing a Decision service Related information: Uninitialized variable or NullPointerException in a Java snippet 159 .returnProcessedException(ExceptionHandler.core.http.servlet.java:310) at com.lombardisoftware.servlet.ExceptionHandler.java:738) at javax.HttpServlet.doError(ControllerServlet.servlet.core.RegexExceptionRewriter.ControllerServlet.servlet.service(HttpServlet.rewrite(RegexExceptionRewriter. Make sure the object has been initialized.service(HttpServlet.core.asTeamWorksException(TeamWorksException.Detail message: Object CustomerName not found at run time during execution.lombardisoftware.java:134) at javax.ControllerServlet.lombardisoftware.servlet.ControllerServlet. at com.java:152) at com.http.lombardisoftware.TeamWorksException.java:129) at com.java:76) at com.doPost(ControllerServlet.lombardisoftware.doCommon(ControllerServlet. or create a new Rule Studio project. then click Finish. C. assume that the rules you wrote for the AlertRules component also apply to other processes in your organization. complete these steps: 1. click the Export icon.Scenario: Exporting rules to a Rule Execution Server This scenario shows you how to export. click the Decisions tab to open the rule editor. Click Select archive file. In the AlertRules component panel. E. Using IBM WebSphere ILOG Rule Studio. D. You can migrate the rules that you created in Process Designer to a business rules management system (BRMS) such as IBM® WebSphere® ILOG® JRules. Click File > Import > General > Existing Projects into Workspace. 2. Procedure To export rules for use in Rule Studio and the Rule Execution server. Export the BAL rules from your Decision service. so you want to share the rules with your co-workers. import the project . Enter a name for the export file. your business process definition includes a Decision service called NotificationRulesService. D. C. In the Save As window. import them into Rule Studio. You can find more information about exporting rules in the related topic about exporting rules for use in Rule Studio. Click Browse to navigate to the location where you saved the exported rule project file and select the file. You can find more information about importing rules in the related topic about configuring a remote decision service. You can export the rules you created in Process Designer. Upon completion of that scenario. Make sure that you are editing the NotificationRulesService Decision service and the AlertRules BAL Rule component. which contains a BAL Rule component called AlertRules. and then connect your Decision service to the RES using a JRules Decision Service component. B. For the purposes of the current exporting scenario. Import the rules into Rule Studio. 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. 160 . migrate and connect BAL rules to a rule execution server (RES). deploy the rules to a Rule Execution Server (RES) . Select an existing project where the rules will be imported. navigate to the location where you want to save the exported rule file. A. B. who are developing business rules using IBM WebSphere ILOG JRules. In the menu bar above the rule editor window.zip file to create a new Rule Studio project. then click Save to specify the location. A. D. and place it in the same location as the deleted BAL Rule component. Replace the BAL Rule component with a JRules Decision Service component. then click Implementation in the Properties tab. Click Generate Types. Select the new JRules Decision Service component. A. enter the following information to connect to the Rule Execution Server that contains the rules that you want to use. click to select each variable that you want to create in your Decision service and then click OK. E. Make sure that you are editing the NotificationRulesService Decision service. the JRules Decision component establishes a connection between Process Designer and the Rule Execution Server that contains the imported rule project. click to select each variable that you want to create in your Decision service and then click OK. You can find more information about adding a JRules Decision Service component in the related topic about configuring a remote Decision service. G. select the Rule App that you want from the menu. When you specify the correct rule execution server and port settings. A. A. C. Click the Properties tab in the JRules Decision Service panel. Add a JRules Decision Service component the Decision service and connect it to the RES.User name: Enter a user name if the JRules server requires a secure connection. Drag a JRules Decision Service component from the palette to the service diagram. D. In the Discovery section. In the Create variables for auto-mapping window. 4. . .SOAP Port: Specify a port for the SOAP connection if the Rule Execution Server is running on WebSphere Application Server. C. B. Configure your Decision service to include a JRules Decision Service component. H. Click the auto-map icon in upper right corner of the Output Mapping section. Deploy the rules to the rule execution server (RES). click Data Mapping. In Rule Studio.3. Remove the AlertRules BAL Rule component that contains the rules you exported. F. see the related topic about deploying from Rule Studio in the IBM WebSphere ILOG JRules BRMS Information Center. B. E.Server: Select the Rule Execution Server (RES). For more information. Click the auto-map icon in upper right corner of the Input Mapping section. 161 . I. B. Reconnect any sequence lines to other activities or services. 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. . Select an existing Rule Execution Servicer and deploy the RuleApp to the server. In the Properties section. Click Connect.Password: Enter the password if the JRules server requires a secure connection. In the Create variables for auto-mapping window. F. In the Rule section. . then select the version that you want to use. select the RuleApp which contains the AlertRules and click Deploy a RuleApp to one or more Rule Execution Servers. 5. 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. What to do next After completing the scenario. see the related topic about testing a Decision service.6. For more information about testing and debugging a Decision service. Save the updated 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 . that represents the component you want to export. 8. you must be in the IBM® Process Designer desktop editor.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. For more information about importing a rule project into ILOG Rule Studio. navigate to the location where you want to save the exported rule file. the business logic can be exported without modifications to IBM WebSphere ILOG JRules Rule Studio. the business process in Process Designer can consume the resulting rule application using a remote decision service provided by JRules. Open a process application in the Designer view. in a situation where the business logic reaches levels of complexity not supported within IBM Business Process Manager. importing into Rule Studio. you can replace the BAL Rule in the Decision service with a JRule Decision Service. Procedure To export a rule component that contains a single rule or multiple rules. and deploying the rules on a Rule Execution Server. To keep the Decision service connected to the rules as you work on them in Rule Studio. then click Save. In the Save As window. Make sure that you are working in the Decision service that contains the rule component you want to export. 6. 4. Refer to the related topic "Configuring a remote Decision service" for information about performing this procedure. After exporting the rules. business rules can be fully developed and implemented using Process Designer. About this task Process Designer provides the capability for non-developers to express business logic using Business Action Language (BAL) in business rules. click the Export icon. such as a BAL Rule. complete these steps: 1. Enter a name for the export file. Before you begin To perform this task. Open the Process Designer desktop editor. In the menu bar at the top of the rule editor window. 2. Results The export function produces an Eclipse project file with a . click to select the component icon. Click the Decisions tab. refer the related topic "Importing a rule project in Rule Studio" in 163 . The export procedure produces a complete business rules project suitable for continued work within JRules. However. In most cases. 5. In the Decision service diagram.zip extension. 3. 7. What to do next You can import the rule project file into ILOG Rule Studio. Parent topic:Building a Decision service Related information: Importing a rule project in Rule Studio 164 .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. . Click Browse to navigate to the location where you saved the exported rule project file and select the file. enter the following information to connect to the Rule Execution Server that contains the rules that you want to use. import the project .Configuring a remote Decision service You can include a rule application from a remote ILOG JRules Rule Execution Server in your Decision service. . Reconnect any sequence lines to other activities or services. 4. When you specify the correct rule execution server and port settings. 4. 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. Specify a port for the SOAP connection if the Rule Execution Server is running on WebSphere® Application Server. Select an existing project where the rules will be imported. In the Discovery section. 2. then click Finish. For more information.Table 1. and imported the rule project into IBM WebSphere ILOG Rule Studio. 165 .Using IBM WebSphere ILOG Rule Studio. or create a new Rule Studio project. see the related topic "Deploying from Rule Studio. Drag a JRules Decision Service component from the palette to the service diagram.zip file to create a new Rule Studio project. 3.Export the rules to an Eclipse rule project file. Before you begin . Deploy the imported rules to the Rule Execution Server. 5. Select the new JRules Decision Service component. See the related topic "Setting environment variables" for more information. 1. then click Implementation in the Properties tab. 3. and place it in the same location as the deleted BAL Rule component." A related link is provided. you can configure your Decision service to include a JRules Decision Service component. the JRules Decision component establishes a connection between Process Designer and the Rule Execution Server that contains the imported rule project. Remove the BAL Rule component that contains the rules you exported. 2. Procedure 1. Click Select archive file. Make sure that you are working in the Decision service where you want to add the JRules Decision Service. About this task After you have exported rules in a rule component from IBM® Business Process Manager. Click File > Import > General > Existing Projects into Workspace. user name. 7. In the Rule section. Click the auto-map icon in upper right corner of the Input Mapping section. so variables can be used to provide those values. 14. listing the private variables needed for input parameters from the selected Rule App. Enter the password if the JRules server requires a secure connection. 12. Click Generate Types. the menu is not populated. In the Properties section. Click Finish when type generation is complete. Save the updated Decision service. The Create variables for auto-mapping window opens. 13. make sure that the Generate request/response wrapper types option is not selected.User name Password Enter a user name if the JRules server requires a secure connection. In this case. In the Generating Types window. Click to select each variable that you want to create in your Decision service and then click OK. The Create variables for auto-mapping window opens. 6. Click Next. then select the version that you want to use. and password fields accept embedded JavaScript expressions. 15. manually enter the name and version of the Rule App and Rule Set that you want to use. The SOAP port. listing the private variables needed for output parameters from the selected Rule App. If a secure connection to the Rule Execution Server has not been established. Parent topic:Exporting rules for use in Rule Studio Related information: Deploying from Rule Studio 166 . click Data Mapping. 8. Click to select each variable that you want to create in your Decision service and then click OK. select the Rule App that you want from the menu. Click Connect. 10. The names must be accurate for the next step to work. Click the auto-map icon in upper right corner of the Output Mapping section. 16. 11. 9. the web service will treat the service called as it would any other generic service. is a more efficient representation of it in your business process model. Conversely.5. WebSphere Operational Decision Management 7. Each time a JRules server version changes. 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 you begin To perform this task.If you connect to a Rule Execution Server that is running on WebSphere Application Server. This secure connection enables you to choose the applications and rule sets that you want to use from the Rule Execution Server. or IBM Operational Decision Management server. It has a closer conceptual mapping to the JRules decision service called and. and password.Adding a JRules Decision Service component to a service When building a Decision service in Process Designer. then you cannot list the rule applications and rule sets available on that Rule Execution Server. you can successfully generate types as described in the following 167 . In this case.1. you must be in the IBM® Process Designer desktop editor. therefore.For a secure connection to a Rule Execution Server running on WebSphere® Application Server. you will need to modify the web service. If the names that you provide are accurate. About this task IBM Business Process Manager integrates with IBM WebSphere ILOG JRules by providing a JRules Decision Service component. but the Rule Execution Server is not properly configured for security or you are not able to provide the SOAP port. you can manually enter the names of the rule applications and rule sets that you want to use. user name. A JRules Decision Service component can handle decision services hosted on either a WebSphere ILOG JRules BRMS 7. you can include decision services available on an ILOG JRules Rule Execution Server in your implementation. review the following requirements: . 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. This rule component enables you to use rule applications available on a JRules Rule Execution Server for your IBM BPM implementations. . the web service has no corresponding model representing the JRules decision service called. you must provide the SOAP port and. 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. Before using the JRules Decision Service component in your Rules service. if necessary. the user name and password for the Rule Execution Server. that is. In this case. 4. if necessary. select the Rule App that you want from the menu. 3. Click Finish when type generation is complete.If you connect to a Rule Execution Server that is running on an application server other than WebSphere. complete these steps: 1. Drag a JRules Decision Service component from the palette to the service diagram. If a secure connection to the Rule Execution Server has not been established. If the names that you provide are accurate. so variables can be used to provide those values. make sure the Generate request/response wrapper types option is not selected. enter the following information to connect to a Rule Execution Server that contains deployed rule applications (Rule Apps) that you want to use. if necessary. 7. user name. The names must be accurate for the next step to work. 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. 9. Click Generate Types. With the JRules Decision Service component selected. then select the version that you want to use. 11. you cannot list the rule applications and rule sets available on that Rule Execution Server. for a secure connection. 6. Click Next. 10. Enter the user name to use. 2. .Table 1. In the Rule section. Enter the password to use. you can manually enter the names of the rule applications and rule sets that you want to use. you can successfully generate types as described in the following procedure. The SOAP port. Create a Decision service. click Data Mapping. 168 . In this case. 8. Procedure To build a Decision service that includes an JRules Decision Service component. In the Generating Types window. for a secure connection. Open the Process Designer desktop editor. Specify a port for the SOAP connection if the Rule Execution Server is running on WebSphere Application Server. 12. In the Properties section. Click Connect. manually enter the name and version of the Rule App and Rule Set that you want to use. the menu is not populated. In the Discovery section. Open a process application in the Designer view. and password fields accept embedded JavaScript expressions. click the Implementation option in the Properties tab.procedure. 5. 14. Click the auto-map icon in upper right corner of the Output Mapping section. 17. listing the private variables needed for input parameters from the selected Rule App. Use sequence lines to connect the JRules Decision Service component to the Start and End Events. What to do next You can nest this Decision service in any other service within your process application that requires the same logic. 18. Click to select each variable that you want to create in your Decision service and then click OK. Be sure to adjust the input and output variables as required for each implementation. listing the private variables needed for output 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. Save the new Decision service. 16. The Create variables for auto-mapping window opens. 15. Click the auto-map icon in upper right corner of the Input Mapping section. The Create variables for auto-mapping window opens. 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 . 7. This expression may contain any valid JavaScript.If you use the Activity Wizard to create a Decision service.The double-dash (-) value in a variable field indicates that any variable value is considered a match. 6. Click Select next to Variable Type and select the type from the list. . 8. Click the Properties tab. Procedure 1. About this task The Decision Table component contains a table with a rule condition in each row. 9. Replace Untitled1 in the Name field with approvalRequired . 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. 2. Click Select next to Variable Type and select the Boolean type from the list. Open a process application that contains a business process definition (BPD).Adding a Decision Table component to a service You can add a Decision Table component to a service. the JavaScript expression that you provide as the action is started. you can choose existing variables to add as input and output. 170 . you might not use the same steps or names. Open the Process Designer desktop editor. . Before you begin To perform this task. Drag the Decision Table component from the component palette to the service diagram. 3. using the JavaScript expression associated with the first condition that evaluates to true. . Each row in the table represents a Boolean condition that will evaluate to true or false at run time. 5. you must be in the IBM® Process Designer desktop editor. then enter ExpenseApproval as the Decision Table component name. 11. right-click an activity and select Activity Wizard from the list of options. Replace Untitled1 in the Name field with request. For your own implementation. Click the Variables tab. Click Add Private. Create a Decision service. The steps in this procedure demonstrate how to add a Decision Table component to a decision service using example values.When a rule evaluates to true. 4. You should use the Activity Wizard when you start with an existing activity and want to quickly create a service to implement the activity. 12. Click Add Input to add variables to the service.A rule only executes the JavaScript expression once per a rule. To access the wizard. 13. 10. Click the Decisions tab to open the rules editor. In the Action Requirement field for the third rule (row). click the plus sign to add a variable (column) to the first rule (row). 23. Make sure the first rule (row) is selected because you want to add another variable (column) to this rule. 27. enter the following JavaScript for the Auto Approval action:tw. or move conditions in the table. 15. Use the Sequence Flow tool to connect the Decision Table component and the Start and End events. In the rules editor. 17. In the rules editor. Click the Diagram tab. click the second row to select it. click the Action section to expand it. In the rules editor. 25. select type from the request structure.Decision Table controls You can use the toolbar options in the conditions editor window to add. The . 24. remove. 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 . 22.for both the amount and type. In the Action section.Specifying variable values using JavaScript You can use JavaScript in rules to set variable values. 20.value in a variable field indicates that any variable value is considered a match.14. . click the plus sign again. . 19.local. 18. type Auto Approval . 26.approvalRequired = false. . Create a catch-all rule by typing . From the list of available variables. From the list of available variables. In the rules editor. 21. In the Action Requirement field for the first rule (row). 28. enter the following JavaScript for the Action: tw. 16.approvalRequired = true. In the rules editor.local. Create a new rule stating that employee expenses of more than $60 require approval. click the third row to select it. For the Requires Approval requirement. Type >250 as the variable value.Authoring rules using JavaScript in a Decision Table component You can create rules using JavaScript in a Decision Table component. Type "director" as the variable value. select amount from the request structure. type Requires Approval . 6. click the plus sign to add a variable (column) to the first rule (row). The rules editor includes the rule shown in the following image: 172 . From the variables displayed. you might not use the same steps or names. and edit the component parameters as described in the related topic "Adding a Decision Table component to a service. Type >250 as the value. Procedure 1." 5. pick the type variable from the request structure. For your own implementation. Before you begin To perform this task. Open a process application that contains a business process definition (BPD).Authoring rules using JavaScript in a Decision Table component You can create rules using JavaScript in a Decision Table component. 4. click the Action section to expand it. 9. 10. In the Action Requirement field for the first rule (row). 7. In the rules editor. About this task The following steps describe how to create a sample business rule using the Decision Table editor and JavaScript. 12. Type "director" as the value. Make sure the first rule (row) is selected because you want to add another variable (column) to this rule.approvalRequired = true. In the rules editor. Open the Process Designer desktop editor. pick the amount variable from the request structure.local. Drag a Decision Table component from the palette to the Decision service diagram. Create a Decision service. 3. 2. From the variables displayed. Click the Decisions tab to open the rules editor. type Requires Approval. 11. 8. click the plus sign again. In the rules editor. you must be in the IBM® Process Designer desktop editor. The sample is a singlefunction rule that can be called from any other service. 14. enter the following JavaScript code for the Action: tw. 13. For the Requires Approval requirement. The rule in the sample is used to determine whether approval is required for certain employee expenses. refer to the related topic "Specifying variable values using JavaScript." 19. 17. The . For more information about the controls in the decisions editor window. 18.approvalRequired = false. enter the following JavaScript for the Auto Approval action: tw. In the Action section. such as the up and down arrows.for both the amount and type. Name the Decision Table component and save your work. Create your catch-all condition by typing . 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. type Auto Approval. Use the Sequence Flow tool to connect the Decision Table component and the Start and End events. refer to the related topic "Decision Table controls. click the second row to select it. 16. In the rules editor. click the third row to select it. In the rules editor." 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 . 20.value in a variable field indicates that any variable value is considered a match. In the Action Requirement field for the third rule (row).local. Create a new rule so that expenses of more than $60 for employees requires approval.15. 21. Click the Diagram tab. The rules editor includes the rules shown in the following image: For more information about specifying variable values using JavaScript. remove. Table 1. Parent topic:Adding a Decision Table component to a service 174 . Move the selected rule (row) up or down in the table or remove the selected rule (row) from the table.Decision Table controls You can use the toolbar options in the conditions editor window to add. Toolbar options in the conditions editor window Option Description Add a new variable (column) or remove the selected variable (column) from the rule. or move conditions in the table. or a number between 5 and 10 (inclusive) Matches the Boolean value true Matches the Boolean value false Parent topic:Adding a Decision Table component to a service 175 .5..Specifying variable values using JavaScript You can use JavaScript in rules to set variable values.10} true false Description Matches the exact string ok (no quotation marks) Matches the exact number 1.5} {1.10} !={1.. "B"} 1.4 Matches either of the strings A or B Matches anything except the strings A or B Matches any number between 1 and 5 (inclusive) Matches any number greater than 3 Matches any number less than 3 Matches any number greater than or equal to 3 Matches any number less than or equal to 3 Matches 1.5 >3 <3 >=3 <=3 {1.4 {"A". 3.5.3.3. or 5 Matches 1. 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. 3.. or any number between 5 and 10 (inclusive) Matches any number except 1.3. 3. "B"} !={"A". which is used to author rules in IBM® Business Process Manager. and the operators that you can use in rule statements to perform arithmetic operations. Parent topic:Building a Decision service Related reference: BAL Reference. is available in the IBM WebSphere ILOG JRules InfoCenter. IBM WebSphere ILOG JRules InfoCenter 176 . For more information.BAL reference A reference guide to the Business Action Language (BAL)." A related link is provided. and compare expressions. The BAL language reference topics list the predefined BAL constructs that you can use to build business rules. in the section "Business Action Language (BAL). refer to the related topics in the IBM WebSphere ILOG JRules InfoCenter. associate or negate conditions. SQLResult . .Decision service limitations Some functions and variables are not supported in a Decision service.XMLNodeList The following types of rule components are not supported. or stateful execution are not supported.Decisions that require complex algorithms such as chaining.Multi-channel decisions are not supported. . .You cannot create complex rules that use decision tables and Business Action Language (BAL) rules in a single rule component. .XMLElement . Rete. Parent topic:Building a Decision service 177 .Decisions that use methods. . When you are creating or modifying rules using the rule editor.XMLDocument .Decisions that reference runtime process instance data cannot be exported for use in IBM WebSphere ILOG JRules Rule Studio. or are supported with some limitations: .The rule editor does not support the following business objects (variable types): .You cannot write rules that include behaviors (methods). the following limitations apply: . custom verbalization and model abstraction are not supported. .The rule editor does not support rules that include data with complex (many-tomany) relationships. only sequential execution is supported. You then expand the client-side human service by adding more coaches and variables. For information. Create the client-side human service artifact. Open the Process Designer desktop editor. 2. clientside scripts. In general. Open a process application in the Designer view.IBM Process Designer displays the diagram of the service with the default Start Event and End Event components. see Building a client-side human service and Implementing a BPD task using a client-side human service. To create services. Within a client-side human service. You can do this from the navigation tree or you can do this from the activity wizard. For example. 4. and other details in later iterations. About this task Building a client-side human service is an iterative process in which many of the steps can be done in any order. dashboards. While client-side human services flow entirely in the web browser. The steps in the procedure are in a suggested order but typically you will go back and forth through the steps as you iteratively build the client-side human service implementation. Before you begin To perform this task. enter a name for the service and click Finish. and services to create a service flow that is run entirely in a web browser. you must be in the IBM® Process Designer desktop editor. decisions. Access to process applications and toolkits is controlled by users who have administrative rights to the repository. see Managing access to the Process Center repository. For more information.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. Remember:IBM BPM also has heritage human services. Process Designer opens the new client-side human service in a web browser. Similarly. In New Service. you could create a simple client-side human service that has a couple of coaches and variables and test it in one iteration. heritage human services instead flow on the server. you create a flow. Procedure 1. you can use coaches. you could create some variables immediately and create other variables as you need them. or user interfaces. 3. For more information. see Difference between client-side human services and heritage human services. 178 . client-side scripts. you must have access to a process application or toolkit in the Process Center repository. and then test and fix problems. create the user interface through one or more coaches. Case management functions are only available if you have IBM BPM Advanced with the Basic Case Management feature installed. For information. the user sees the Process Portal home page when the clientside human service is complete.Building coaches . see Adding HTML meta tags to client-side human services for mobile device optimization. Optimize how users see the coaches by adding HTML meta tags to the clientside human service. define its properties. see Mapping input and output data for an activity or step. the user sees the default page of the application that launched the client-side human service. map the input and output data. see Saving the state of a client-side human service during execution . For information. Run the client-side human service and debug any errors that might occur. To postpone work in a coach. add coaches. For information. define the data used by artifacts within the client-side human service. For information. If the client-side human service is within a BPD or a case type activity.5. Parent topic:Building services 179 . if the user started the client-side human service in Process Portal. called services. For information. Connect them to define the flow for the client-side human service. 15. see Navigation options for after service completion. By default. In the Diagram page. add a postpone pattern to the client-side human service diagram. 12. This data consists of data passed into the client-side human service. see Exposing client-side human services.Implementing exclusive gateways in client-side human services . see Validating client-side coaches using client-side validation. and exclusive gateways to the client-side human service diagram. the client-side human service is not exposed. client-side scripts. see the following topics: . you can also make it available in Process Portal or through a URL. add a coach validation pattern to the client-side human service diagram. For information. If the client-side human service is within a BPD or a case instance and you want users to be able to resume work at a particular point with minimal loss.Calling another service from a client-side human service 8. 9. 13. 6. In the Variables page. see Enabling work to be postponed and resumed at run time. see Running and debugging client-side human services. However. 7. For information. which means that it is contained within a BPD or case type. Set how users interact with the client-side human service by setting its exposure. By default. select a flow line in the diagram and then select to save the execution context. For information. see Declaring variables for a human service. For each element in the client-side human service diagram. and data passed out of the client-side human service. Set what happens after the client-side human service completes. To validate the data in a coach. For information. 11. data used only within the service. 14. For information. 10. For example. 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. users see the web-based form that is defined in the coach layout. For more information. 4. Before you begin To perform this task. 7. see Managing access to the Process Center repository. . and coaches. When the flow reaches a coach. set whether each business process variable is an input or output of the heritage human service. create the heritage human service using the library and then start the procedure at step 7. and then define the heritage human service that is associated with that activity. you must be in the IBM® Process Designer desktop editor. To create services. click Next. decisions. select Create a new Service or Process. Open a process application in the Designer view. 3. Right-click the activity and select Activity Wizard from the list of options. Open the Process Designer desktop editor. In the Setup Activity page of the wizard. Activities dropped into any lane but System have the default heritage human service implementation.IBM Process Designer displays the diagram of the service with the default Start Event and End Event components. enter a name for the service and click Finish. If you are not creating the heritage human service for a BPD or you want to create the heritage human service first. you replace this default heritage human service with your own. events. 2. In a BPD diagram. Procedure 1. drop an activity into a non-system lane and then rename the activity. if you have business process variable that is named request and the heritage human service is to collect data to create that request for the server. For example. About this task A heritage human service consists of a server-based flow that can include scripts. In the remaining steps. 6. In New Service. add an activity. The form displays processrelated data to users and collects input from those users. The steps in this procedure start from the business process definition diagram. 180 . set its Input to false and Output to true. If the BPD has variables that are defined.. you must have access to a process application or toolkit in the Process Center repository. 5. In the Parameters page of the wizard. The heritage human service then provides the data for the subsequent process activities to act upon. Access to process applications and toolkits is controlled by users who have administrative rights to the repository. see Building coaches. In the Variables page. see Coaches toolkit: Button stock control.If you added one or more business process variables that are primitive types. Click Save in the main toolbar. When you are building the coach.If you added one or more business process variables that are complex types and they have an associated coach view. 10. Click Finish.8. set the exposure in the Overview page of the service. the coach has a placeholder message for each of these variables. To view the service flow in a web browser. wrap the code using the other type of quotation mark. 14. see Exposing heritage human services. For more information. if the HTML values use double quotation marks. in the Process Admin Console or as a page in Process Portal). The coach in the diagram has the following default content: . you replace each placeholder with a coach view that is appropriate for the variable and how the coach is using it. to expose the heritage human service as a page in Process Portal. 15. You can use the Button stock control to fire a boundary event. The activity now has an associated heritage human service that includes a simple diagram. For example. If you want to expose the heritage human service outside of the business process (for example. . For more information. Iterate through steps 7 . 9. the coach has an appropriate stock control in the layout for each of these variables. For example. create the user interfaces used in the service flow. In the Coaches page. Restriction: You cannot wire out from a coach unless the coach (or one of its child coach views) contains at least one element that fires a boundary event. 12.11 until the service flows correctly and the user interface is correct.Tip: If you provide HTML code as a default value for a variable. the coach has that coach view for each of these variables. or you can create a custom control that fires a boundary event. add business process variables to support your service flow. This default content is for your convenience and you can use it or replace it.If you added one or more business process variables that are complex types and they do not have an associated coach view. . . you could replace the placeholder with a Customer View coach view that displays customer data in a set of text fields. if you have a Customer business object.If you are building the heritage human service in a toolkit instead of in a process application. click the button. For more information. In the heritage human service diagram.A button that provides the boundary event that you can use to wire the coach to the end node. 13. See Service components in Process Designer for information about the elements that you can add to the diagram. you must also do the 181 . create the service flow by adding elements from the palette and wire the elements together to create a flow. wrap the entire code in single quotation marks as shown in the following example:'<font color="#f08080"><b>Some text!</b></font>' 11. changing. Activate the toolkit snapshot. Parent topic:Building services 182 . C. Add the toolkit snapshot as a dependency to a process application. Create a snapshot of the toolkit. For more information. see Creating. see Activating snapshots for use with IBM Process Portal. and deleting a toolkit dependency in the Designer view. B.following steps: A. For more information. To create services. Open the Process Designer desktop editor. you must be in the IBM® Process Designer desktop editor. Access to process applications and toolkits is controlled by users who have administrative rights to the repository. Parent topic:Building services Related information: Calling Ajax services from coach views Building an Ajax service with heritage coaches 183 . Configure the components in the sequence flow. Open a process application in the Designer view. you must have access to a process application or toolkit in the Process Center repository. if you are using a Server Script component. Procedure 1. see Service components in Process Designer. see Managing access to the Process Center repository. 5. 7. 3.For more information about components.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. the following Ajax services are provided in the Coaches (8. Example To view an example of an Ajax service. For more information. Add variables that the service will use as input or output. The Ajax service is available for use in Coach Views. Save changes. Before you begin To perform this task. enter a name for the service and click Finish. and Default Selection Service. 4.IBM Process Designer displays the diagram of the service with the default Start Event and End Event components. for default selection values in selection lists. 2. For example. You can also add private variables. Add components to the service diagram and then set up the sequence flow. Default Autocompletion Service. 6. In New Service. add a script in the Implementation properties. such as for auto-completion in text fields. See Declaring variables for a BPD or a service in Process Designer for information.0) toolkit: Coaches Localized Messages Loader. and so forth. and add the appropriate components to the service and then connect the components to create the flow. For more information. Before you begin To perform this task. Procedure 1. Select the Diagram tab. . . you must have access to a process application or toolkit in the Process Center repository. 2. enter a name for the service and click Finish. In particular. 5. you can build an Integration service that calls a web service to display the list of options. add one or more of the following components: .Web Service Integration component. See Declaring variables for a BPD or a service in Process Designer for information. Configure the components in the flow. Access to process applications and toolkits is controlled by users who have administrative rights to the repository.Content Integration component. see Creating outbound integrations to web services.Building an integration service Build an integration service when you want a flow to interact with an external system. Tip: You can also use the Invoke UCA component for integration. 4. For more information about inbound and outbound integrations. In New Service.IBM Process Designer displays the diagram of the service with the default Start Event and End Event components. you must be in the IBM® Process Designer desktop editor. For information about the components that you can add to the diagram. see Managing access to the Process Center repository. Integration services are the only services that can include Web Service Integration and Java Integration components as well as content integration. .Java Integration component. This action attaches the service to the component. For the integration components listed in the previous step. In that case. Select the Variables tab. 6. see Building a service that integrates with an ECM system or the IBM BPM document store. Java and databases. you may want users to choose from a list of products available from a common site on the internet. see Service components in Process Designer. Open the Process Designer desktop editor. Open a process application in the Designer view. In 184 . To create services. and add the variables that your integration service will use as input or output and also add private variables that the service will use. For information about integrating web services. See Undercover agents. 3.Nested service component by dragging an integration service or other service onto the diagram. configure them so that they interact with the external system. About this task For example. For information about this component and how to configure it. see Integrating with web services. the results for each combination of input parameter values are kept in the cache for 12 hours. when caching is enabled. select Enable caching of service results. however you must take care when you decide how long to cache results for. enable and configure the service result cache.Use to suggest mappings. If the automatic mapper does not find a variable. you can create a private variable for the mapping.Restriction: The service result cache setting works only for top-level services that are called directly. use the Days. Because you already created the input and output variables for the nested service. C. Click the Data Mapping option in the properties. Java Integration. Select the Overview tab. . Content Integration. The cache configuration fields are displayed. By default. Minutes. the cache stores up to 4096 results. for the Web Service Integration. Hours. then in the Service Result Cache section. In the Output Mapping section. To change the caching period. in the Cache results for section. and might need to tune the size of the cache to avoid memory problems. the Data Mapping tab includes these variables. Example See the integration services included in the System Data (TWSYS) toolkit for implementation examples. and nested service components.xml file. map the data used in the task flow to the input and output for the component: A. B. you can map each variable using one of the following ways: . 7. A.Important: You might be able to improve the performance of some services by using the cache. If you want the results of the service to be cached for unique combinations of input parameter values.Use and then select the appropriate variable. Java and databases Examples of building services with heritage coaches Integrating BPDs with IBM Case Manager cases Integrating with Enterprise Content Management (ECM) systems 185 .particular. do similar mappings for the output variables. If a service is called within another service. the cache setting does not apply. You can change the size of the cache by setting a different value for <service-result-cache-size> in the 100Custom. From the Input Mapping section. inside the <server merge="mergeChildren"> section. B. Parent topic:Building services Related information: Integrating with web services. and Seconds fields to select the duration that you want. By default. output. For example.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). 3. Note: Advanced integration services are available only with IBM Business Process Manager Advanced. For example. For more information. Access to process applications and toolkits is controlled by users who have administrative rights to the repository. Procedure 1. since you may want to share this and other advanced integration services with many business processes. Before you begin An advanced integration service is a collaboration between a business user working with IBM Process Designer and an integration developer working with IBM Integration Designer. In the Parameters section. Checking with an integration developer. and error parameters. see Managing access to the Process Center repository. Optional: In the Documentation field. add a description for your service. Open a process application in the Designer view. you must be in the IBM Process Designer desktop editor. As suggested in Best practices when using IBM Integration Designer and IBM Process Designer together. An error parameter identifies an error or fault that might be thrown by the service 186 . You could create an advanced integration service that would use this Integration Designer service as an activity in your business process. Open the Process Designer desktop editor. 2. To perform this task. you might select a toolkit to contain all your advanced integration services. About this task To build an advanced integration service. your business process may need a list of computer parts in your warehouses in Canada. To create services. enter a name for the service and click Finish.An input parameter defines the name and type of data your business process sends to the service in Integration Designer.IBM Process Designer displays the diagram of the service with the default Start Event and End Event components. In New Service. An output parameter defines the name and type of data your business process receives from the service in Integration Designer. 5. you must have access to a process application or toolkit in the Process Center repository. 4. follow these steps. you realize that a service is being built in Integration Designer to query the Canadian warehouses and return an inventory list of the computer parts available. collaborate before defining your advanced integration service. add input. If used by a system task. The Advanced Integration Service section contains fields used in Integration Designer that will be initially empty with the exception of Can be used with service? The fields will be filled in when the service is implemented in Integration Designer. If the implementation cannot be used with a service. Selecting Is List means the parameter is an array (contains a set of data).If used by a user task. .Operation name: The name of the operation of the service to be invoked. 7. In the Parameter Type field. . .An advanced integration service can always be used by a Business Process Definition whether the Can be used as service field is set to Yes or No. An export is the endpoint to be used when invoking the service.Can be used with service?: Not all implementations of advanced integration services can be used with a service. it is run by the system user. . It can also be used by the following services if the field is set to Yes: a general system service. set the data type for the parameter. it behaves in the following way: .Export name: The name of the export of the module that exposes the service implementation.Asynchronous style with a request-response operation type: No.designed in Integration Designer. it is assigned as specified via the assignments of the user task. 187 . any user selected will require authentication. Select the user you are currently authenticated as and enter your credentials. Do not use an advanced integration service with these services if you see a No in this field or these services will experience unexpected behavior. If used by a user task. If you want to catch a specific error using an error event in your process model. Can be used with service? can also be changed at that time depending on the implementation in Integration Designer. . . In emulation. From the menu. . select File > Save All Results An advanced integration service can be used as implementation of a user task or a system task.If used by a system task then it will use the All users group. 6. An advanced integration service can also be emulated. enter an error name that matches the error code in the catching error event. this field will be set to No. 8. . Add a description for the parameter in the Documentation field.Synchronous style with a one-way operation type: Yes. Save your work.Asynchronous style with a one-way operation type: Yes.Module name: The name of the module in Integration Designer containing the service implementation.Synchronous style with a request-response operation type: Yes. it is assigned as specified via the Assignments of the user task. An Open in Integration Designer button lets you see the implementation created in Integration Designer. It can only be used if Integration Designer is available. a human service or an integration service. When All users is shown in emulation. . The Yes or No value itself is determined by the preferred interaction style and operation type used by the associated export in Integration Designer. Your service and its implementation by Integration Designer are decoupled. notify the integration developer who implemented your service. 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.As discussed earlier. What to do next Use the information in Authoring services in IBM Integration Designer to continue developing your advanced integration service. BPEL processes. Parent topic:Building services 188 . 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. and more. You can add services. your service is a collaborative arrangement. Should you move your advanced integration service to another toolkit. monitor models. service-related functions. Prerequisite: To build a General System service. or Content integration). To create a General System service. manipulate variable data. General system services are likely to be called directly from a BPD or from a Human Service. In New Service. Java integration. Parent topic:Building services Related information: Examples of building services with heritage coaches Service types 189 . To create services.Building a General System service Use General System services when you want to orchestrate other background services. 3. such as scripts. General System services can be nested within any other type of service. Access to process applications and toolkits is controlled by users who have administrative rights to the repository. see Managing access to the Process Center repository. and cannot contain Coaches or integration steps (Web Service integration. 4. you must be in the IBM® Process Designer desktop editor. 1. Open a process application in the Designer view. you must have access to a process application or toolkit in the Process Center repository. 2. or perform some other actions that do not require any integrations or business rules. Open the Process Designer desktop editor. and then click General System Service.IBM Process Designer displays the diagram of the service with the default Start Event and End Event components. For more information. General System services can include only basic service components. generate HTML for a Coach. enter a name for the service and click Finish. Click the plus sign next to Implementation. perform the following steps. and timeouts by using timer events To specify when an activity occurs or when another path in the process should be taken.Modeling delays. . .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. or a incoming message from an external system.Handling errors using error events When you design a business process definition (BPD) or a service.Modeling events Events in IBM Business Process Manager can be triggered by a due date passing.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.Modeling event gateways Use an event gateway to model a point in the process execution where only one of several paths can be followed.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. Parent topic:Modeling processes 190 . You can add events to your BPDs that can occur at the beginning. manage errors. use intermediate and boundary events of the timer type. . provide logic to recover from possible errors that might be generated in the runtime application. Use events to track data. . and retrieve information about the execution of your BPDs. . or at the end of a process. . You can use receiving message events to create or interact with BPD instances. . . an exception. depending on events that occur. during.Event types Learn about the types of events available in IBM BPM and when to use each type.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). escalations. For example. 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. a linked process.Use to model the start of a process.) Or.Start event . you can use this implementation option when you intend to use a process as a linked process from another higher level process. . You can include the following types of events in your IBM BPM Business Process Definitions (BPDs): . 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. a subprocess or an event subprocess. Message Ad Hoc Content . (For an example of such a process.Note: For information about implementation options for Start events in a subprocess or event subprocess. see Subprocess types. Start events have the following implementation options: Table 1. Use the Content implementation option if you want an ECM event to kick off a process.Intermediate event 191 .Event types Learn about the types of events available in IBM® BPM and when to use each type. A Start event is automatically included each time you create a business process definition (BPD). see Creating a business process definition (BPD). Use the Ad Hoc implementation option when you need to include ad hoc actions that can be run at any time during process execution. 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. 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). Timer Tracking Error Content 192 . connected with sequence flows. Implementation options for Intermediate events Option Message Description Use the Message implementation option to model a message event that is received or sent. Use the Timer implementation option to model escalation paths or delays in your BPDs. see Handling errors using error events. The Message implementation option is available for events included in the process flow and events attached to an activity. The Tracking implementation option is available only for events included in the process flow. 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. 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. Using a timer event. Use the Content implementation option to model an ECM event that is received. See Modeling timer events for more information. The Error implementation option is available only for events attached to an activity. you can specify a time interval after or before an activity is performed. For an example of how to use intermediate error events.Intermediate events can be attached to activities within your BPDs or they can be included in the process flow. Use the Error implementation option to catch errors and to handle errors with login in the process flow. the event receives only messages. When attached to an activity.. The Timer implementation option is available for events included in the process flow and events attached to an activity. The Content implementation option is available for events included in the process flow and events attached to an activity. Attached intermediate events are known as boundary events.Intermediate events have the following implementation options:Table 2. For example.Use to model the end of a process. If you do not select this option. Delete All Terminated Instance Runtime DataCleans up the runtime state for the executing instance. This setting only applies to top-level process instance cleanup. An End event is automatically included each time you create a BPD. If an entire process instance is terminated. See Using message end events for more information. Error Terminate Message 193 .End event . and is ignored otherwise.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. You can set these options for the terminate event: Terminate Entire Process InstanceTerminates the entire process instance. Use the Message implementation option when you want to send a message. Use the Error implementation option when you want to throw an error to parent processes or to error event subprocesses. only the process that contains the event and its subprocesses is terminated. the process shows a status of Terminated in the Inspector. Use the Terminate implementation option when you want to close running tasks associated with a process and cancel outstanding timers.. See Handling errors using error events for more information. 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. All database states for the runtime instance and any generated tracking data is deleted. Parent topic:Modeling events 194 . However. . 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. use timer boundary intermediate events.Modeling delays. When a running process instance reaches an activity that has a timer boundary event. If any timers elapse while the instance is suspended. For example. The delay ensures that two days pass between the emails and when the sales team starts contacting the customers. Each timer event has an associated timer. About this task In a business process definition (BPD). use timer events to do the following things: . the timer events do not trigger. when a BPD instance suspends.Create a timeout to prevent a flow from waiting indefinitely. you must be in the IBM® Process Designer desktop editor. a timer starts. use intermediate and boundary events of the timer type. the timer event triggers and the sequence flow goes out from the timer event to a subsequent node. All of the timers within the timer events continue to track the passage of time though. . the process follows the sequence flow 195 . escalations. model a delay by using a timer intermediate event between the two activities. When the timer elapses. Normally. their associated timer events wait for the BPD instance to resume before they trigger.Create an escalation to handle when an activity fails to complete in a timely fashion. For modeling escalations. use timer events to control when activities occur within a process flow or when a process flow takes a specific path. Timer boundary events are attached to an activity in a BPD.Create a delay to prevent an event or activity from immediately triggering. That is. and timeouts by using timer events To specify when an activity occurs or when another path in the process should be taken. The time interval for the timer is calculated according to the configuration that you specify in the implementation properties for the timer event. The process waits for the timer in the timer event to elapse before it proceeds to the next node. For modeling delays. when the specified time interval elapses. Before you begin To perform this task. use timer intermediate events that have sequence flow lines that are entering it and sequence flow lines that are leaving it. To create an escalation. For an example. 2. drop the intermediate event into a blank area of the canvas. 4. When you add an event gateway. For information about creating an event gateway. select the activity and check that the outline of the activity includes the event icon. see Hiring tutorial: Add a timer intermediate event in the Hiring Tutorial or see the Hiring Sample. 3. escalation. attach more than one intermediate events to the activity. If the other intermediate events in the event gateway group do not trigger before the timer elapses. . 5.To create a timeout. to start the timer when the due date for an activity elapses. If you want the users to complete the coaches even after the timer elapses. drop the intermediate event onto an activity. The due date is calculated according to the work schedule for the BPD and the priority settings for the activity.To create a delay. you can choose to have the escalation occur only once by clearing the Repeatable check box. see Modeling event gateways. 7. Note: To trigger the timer event before or after a custom 196 . in the Boundary Event Details section clear the Interrupt Activity check box. Procedure To model a delay. Each boundary event triggers a different escalation path. The human service that is associated with the user task has coaches. For modeling timeouts.from the timer boundary event to a subsequent activity. If you are creating an escalation and you want the activity to remain open after the timer is triggered. select Timer. Specify when to start the timer for the timer event by setting the Timer properties: A. . imagine that you create a timer boundary event for a user task. clear the Interrupt Activity check box. or timeout: 1. 6. This action attaches the intermediate event as a boundary event. Process Designer automatically adds a timer intermediate event and a message event to the event gateway group. use timer intermediate events that are included in event gateways. select After Due Date. To verify that you have created a boundary event. You configure the timer intermediate event to specify the timeout period. If you clear the Interrupt Activity check box. Open a BPD in the Designer view. For example. Open the Process Designer desktop editor. Drag an intermediate event from the palette. the timer intermediate event triggers instead. From the list of Intermediate Event types. Select the intermediate event and open its Implementation properties. For more information.To have multiple escalations. see Setting the work schedule for a BPD. . For example. Set what starts the timer with the Trigger On field. drop the intermediate event into an event gateway group. If you are creating an escalation or timeout. 8. Parent topic:Modeling events Related information: Hiring tutorial 197 . use the Tolerance Interval field.For an escalation or timeout. you can enter the JavaScript to determine the custom date in the Custom Date field.date. For example. use the Before or after difference field. create the flow that the process uses after the timer elapses. connect the timer event to the escalation or timeout path. Your JavaScript must return a Date object. The escalation path is the logic that the process performs if the timer elapses before the activity it is attached to finishes. use the Sequence Flow tool to connect the timer event to the rest of the process. Optional: To modify the trigger. the timeout path is the logic that the process performs if the timer elapses before another event in the event gateway group triggers. B. Connect the timer event: . 9. . For example. Optional: To further modify the trigger.For a delay. C. type 1 into the field and select Days from the associated list. which specifies when to start the timer. 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. Similarly. if you want start the timer a day after the due date of the activity. you must be in the Process Designer desktop editor. or can be received by the start event in another process or processes. You can include the following types of message events in your BPDs: Table 1. To learn how to configure message events to send messages. the Event Manager has a defined XML message structure that it must receive from an external system. 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. see Using intermediate message events and message end events to send messages. see Posting a message to IBM Business Process Manager Event Manager.Use as the start event for an event subprocess when you want the event subprocess to be triggered upon receipt of a message. Outgoing messages can be received by a message event in a process.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. Incoming messages can originate from a message event in a process. Prerequisite: To model message events. from a web service that you create. can be sent to call an external service. A BPD can include more than one start message event. from starting an undercover agent (UCA) in a service. For more information about the required message structure. If you want to post a message to the JMS Listener. from a Service Component Architecture (SCA) service. . 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 a new instance of the message is delivered to the process instance. Message that is configured Use to send a message to send (End events can event at the end of a path. A message can cause a process instance to be created. should the execution of the BPD instance loop back and reach the same message event(s). Intermediate events can be attached to activities within your BPDs or they can be included in the process flow.You can configure message events to consume messages. which is connected with sequence flows.Intermediate event Intermediate event End event Message that is configured Use to receive a message to receive event. . Because the message 199 . Before you include any type of message event that uses an undercover agent as the triggering mechanism.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. . you should be aware of the following: . you can cut and paste or copy and paste that message event within the same BPD or from one BPD into another BPD. enable the Consume Message option only for the last message event in the chain of roll-forward message events. or be triggered repeatedly. When a message is consumed. An intermediate event that is attached to an activity. the message is accepted and processing continues-otherwise. 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). If the condition that you specify evaluates to true. it will not be processed again by that message event. which is connected with sequence flows. this message is available for consumption again and is accepted by the message event. and can be received by a running process that contains one or more appropriate message events.Occasionally. You can also use conditions to further control message consumption. Message that is configured Use to send a message to send event. only send messages) When you create a message event. rather than the swimlane. it is stopped. To enable rolling a message forward through multiple message events. Intermediate events can be included in the process flow. If you do. or any other message event in the BPD instance that can accept it. Boundary events can optionally either interrupt and complete the activity. when a message is delivered to a running process. you might need to set conditions on the processing of incoming messages. is known as a boundary event. If the message condition evaluates to true. When the process execution reaches an intermediate message event. otherwise.condition is evaluated before the message values can be passed to the input variables of the process definition. the values are passed from the tw. you can exercise some control over which snapshots use 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.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. .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. . You can override the default target by selecting a check box in the implementation settings for the UCA that carries the event.Using start message events If you want a process or event subprocess to start when a message is received. .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. Parent topic:Modeling events Related information: Modeling event subprocesses 200 . .message. further execution along that path is blocked until an incoming message arrives that matches.message namespace to the BPD input variables. it is passed to the message event. use a Start Message Event in your business process definition (BPD) or inside your event subprocess. if a matching message is stored in the system. the message values are passed to the condition in a special namespace. . or a message end event when you want to send a message at an end of a path. tw. Incoming messages can originate from a message event in a process. . be aware of the following: . Before you begin To perform this task. On the Properties tab. 2. When the record is created. In the Start Event Details section. 5. you might want an employee on-boarding process to start when a record for each new employee is created in your HR system. Otherwise. click Implementation. If you use the same undercover agent for multiple start message events. requesting and creating a security badge. from a Service Component Architecture (SCA) service.If you use multiple start message events in a single BPD. Open a BPD or drill into an event subprocess. the parent instance is completed. For example. 4.When a message is received by a start message event (specifying that an incoming message is to start a process at run time). 3. If the start event is part of an event subprocess. IBM BPM instantiates multiple instances of the BPD. from starting an undercover agent (UCA) in a service. a new instance of the process is created and a unique BPD instance ID is assigned to it. the system sends an event to IBM Business Process Manager. A. 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. clear the selection so that the parent process is not interrupted or completed when the message is received. If receiving and processing the message causes completion of the parent process. from a web service that you create. then drag a Start Event component from the palette onto the diagram. the Start Event Details section shows the following options. 201 . Open the Process Designer desktop editor. when the subprocess reaches its end. When this option is selected. use a Start Message Event in your business process definition (BPD) or inside your event subprocess.Using start message events If you want a process or event subprocess to start when a message is received. Procedure 1. use a separate undercover agent for each. 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. or from a message that you post to the JMS Listener. which is the default setting. select the start event type Message. make sure that the Interrupt Parent Process option is selected. you must be in the IBM® Process Designer desktop editor. C. If Interrupt Parent Process is not selected. If you want. select SCA Service. . F. If you want the incoming message to be consumed after it is received by the message event. For example. 7. the message is accepted and processing continues. based on the name of the event. The generated service interface name is displayed. complete the following actions in the Message Trigger section. . For Triggering Mechanism. Tip: UCAs must have a schedule type of On Event to function as a message trigger. select UCA. If the condition evaluates to false. complete the following actions in the Message Trigger section. the Repeatable option is available. 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. The Durable Subscription check box is not available for start message events. The message object type must be a complex type. If the start message event can be triggered more than once. only for intermediate message events as described in the following section. if the sender of the message is a message end event in another BPD. or leave it to be set automatically when you select a service definition. then select the same undercover agent for both the receiving intermediate event and the sending message end event in the other BPD. Important: The sender and receiver of the message must both use the same undercover agent. To create an undercover agent. To use UCA for triggering a start message event. enable Consume Message. click New to define a new BO type.B. type a JavaScript expression if you want to define conditions under which the message event is processed. 6. a default value is provided. In most cases. B. In the Condition text box. For Triggering Mechanism. the message object type is updated to match the service definition. See Undercover agents. click Select to select a business object (BO) type. click Select next to the Attached Message UCA field. To use an SCA service for triggering a start message event. For Message Object Type. E.If you selected an existing service definition and the message object type was not set. Refer to the bulleted list in Modeling message events to learn more about message consumption. it is restricted to using the NMToken character set.The service identifier is used with the BPD name to generate a unique SCA service for this event point. D. C. processing stops. as shown in the BPD diagram. B. 202 . 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. For Service Identifier. If you enter a name. click New. A. Plus. The business object type that you select determines the output parameters of the start message event. To select an existing undercover agent. A.If you do specify a condition and the condition evaluates to true. select the Repeatable option so that the subprocess can receive multiple messages. special message conditions are not necessary because you should implement each message event with a separate undercover agent. which compatible message events are in the waiting state. D. each incoming message is received by only one of the events. Select the output variable that you want to use to for correlation. click the X (delete) icon. you can break the unintended polymorphism by renaming the duplicate event names and then click X (delete) to restore the default service identifier name. On the Properties tab. C. you can map the employee information from the undercover agent to a local variable in the BPD. However. .To restore the default value.If you specify the same SCA identifier for multiple message events. if different events have identical names (which is shown as an error on the General tab). if the start message event starts an instance of an on-boarding process when an employee record is created in your HR system. Map each output variable to a local variable in the BPD.If you specify the same SCA identifier for multiple message events. depends on whether a correlating process instance is found. A. The value that is assigned to it ensures that the parameter values of the runtime message are passed to the correct BPD instance. B. Making such changes can break data mappings for the events. if multiple start message events specify the same SCA service identifier. Specify the correlation and output mapping.For undercover agents that are implemented using a complex variable rather than a service. 203 . 8. If you use SCA. For example. the associated events are added to the list of events that the definition includes. you can select the complex variable or the top-level child properties of the variable for mapping or correlation. click the variable selector icon to map each output variable to be passed into a local variable in the BPD. This correlation ensures that the parameter values of the runtime message are passed to the correct BPD instance.. and if so. Which event receives the message. any changes to the service identifier or message object type affect all the events that provide the service. . see Using Service Component Architecture to interact with processes. For each variable. Important: It is possible to define unintentionally the same service identifier on multiple events. Open the Correlation and Output Mapping section. For details of the semantics.If you selected an existing service definition. Tip: If your BPD includes more than one start message. or if different service identifiers map onto identical NMToken strings. If such a naming clash happens. Otherwise. click Data Mapping. or whether it is stored for future delivery. the start event that receives the start message is selected arbitrarily. each one should use a different SCA service identifier. the service interface can trigger multiple events in the BPD. For example. . 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. The variable that is selected for correlation is identified by an assignment symbol ( ). Correlation allows IBM BPM to identify the process instance that the message is meant for. you must select a variable to be used for correlating process instances. an employee number might be used to uniquely identify an instance of an on-boarding process. For example. 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 . Selecting this variable for correlation ensures that when the data related to a specific employee number is passed to the event subprocess.If your start message event is inside an event subprocess. When the event is attached to an activity. When the process execution reaches an intermediate message event. Tip: To build a sample inbound integration that includes an intermediate message event included in the process flow. further execution along that path is blocked until an incoming message arrives that matches.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. It can be dragged to the swimlane or attached to an activity. Open a BPD and drag an Intermediate Message Event component from the palette onto the BPD diagram. 4.Tip: When you add message events in a BPD. If you drag an intermediate message event onto an activity. in the Boundary Event Details section. select the intermediate event type Message. you must be in the IBM® Process Designer desktop editor. if a matching message is stored in the system. Open the Process Designer desktop editor. Before you begin To perform this task. which is connected with sequence lines. see Building a sample inbound integration. click Implementation. 2. Select the event type Message. which is connected with sequence flows. About this task For a receiving intermediate message event. 3. it is passed to the message event. A. You can also use a Service Component Architecture (SCA) service as the triggering mechanism. B. Drag an intermediate message event onto the swimlane to create an intermediate message event. be aware of the general information in Modeling message events that applies to all types of message events. the event is known as a boundary event and it is included in the outline of the activity. in the Intermediate Event Details section. otherwise. Procedure 1. select the intermediate event type 205 . If you dragged the Intermediate Message Event component onto an activity. You can change either existing message event type to the other type by dragging it to or from the swimlane or activity. On the Properties tab. you can use an undercover agent (UCA) for the message triggering mechanism. If you dragged the Intermediate Message Event component onto the BPD diagram. Intermediate message events can be attached to activities within your BPDs or they can be included in the process flow. it becomes a boundary message event. D. If the condition evaluates to false. processing stops. make sure that the Interrupt Activity option is selected. Only the most recently received message is stored. The durable messages accumulate. Important: The sender and receiver of the message must both use the same undercover agent. A. For Triggering Mechanism. If you want the incoming message to be consumed after it is received by the message event. Periodically use the BPMDeleteDurableMessages command for deleting durable subscription events. To use an SCA service for triggering an intermediate message event. 206 . 6. select SCA Service. B. When Durable Subscription is selected. special message conditions are not necessary because you should implement each message event with a separate undercover agent. Tip: If you occasionally use inbound messages and undercover agents. consider using durable subscription events. then select the same undercover agent for both the receiving intermediate event and the sending message end event in the other BPD. 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. Plus. select the Repeatable option so that the attached activity can receive multiple messages. click Select next to the Attached Message UCA field. If receiving the message signals completion of the activity. Refer to the bulleted list in Modeling message events to learn more about message consumption. In most cases. the Repeatable option is available. If the intermediate message event is a boundary event. The durable subscription causes the message to be stored until the message event is reached. incoming messages are persisted in the database. type a JavaScript expression if you want to define conditions under which the message event is processed. Tip: Undercover agents must have a schedule type of On Event to function as a message trigger. See Undercover agents. For example. complete the following actions in the Message Trigger section. To select an existing undercover agent. the message is accepted and processing continues. 7. which is the default setting. select Durable Subscription.If you do specify a condition and the condition evaluates to true. A. B. F. if the sender of the message is a message end event in another BPD. clear the selection. For Triggering Mechanism. click New. enable Consume Message. In the Condition text box. so that the activity is not interrupted and completed when the message is received. E. 5. Otherwise. C. use the Boundary Event Details section to specify its behavior: A. If Interrupt Activity is not selected. complete the following actions in the Message Trigger section. If the boundary message event can be triggered more than once. even if you select the check box to make them consumable. 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. To use a UCA for triggering an intermediate message event.Message. select UCA. To create an undercover agent. If you selected an existing service definition.If you specify the same SCA identifier for multiple message events. If such a naming clash happens. C. Open the Correlation and Output Mapping section. you can select the complex variable or the top-level child properties of the variable for mapping or correlation. if different events have identical names (which is shown as an error on the General tab). Which event receives the message. Important: It is possible to define unintentionally the same service identifier on multiple events. which compatible message events are in the waiting state. and if so. B. or leave it to be set automatically when you select a service definition. depends on whether a correlating process instance is found. the message object type is updated to match the service definition.B. C. it is restricted to using the NMToken character set. The variable that is selected for correlation is identified by an assignment symbol ( ). Making such changes can break data mappings for the events. Specify the correlation and output mapping. click Data Mapping. the service interface can trigger multiple events in the BPD. click New to define a new BO type. each incoming message is received by only one of the events. For Service Identifier. any changes to the service identifier or message object type affect all the events that provide the service. If you enter a name. The generated service interface name is displayed. . or if different service identifiers map onto identical NMToken strings. you can either specify a different service identifier name.The service identifier is used with the BPD name to generate a unique SCA service for this event point. This correlation ensures that the parameter values of the runtime message are passed to the correct BPD instance. a default value is provided. based on the name of the event. the associated events are added to the list of events that the definition includes. . 207 .To restore the default value. The value that is assigned to it ensures that the parameter values of the runtime message are passed to the correct BPD instance. However. as shown in the BPD diagram. For details of the semantics. . . For example. Tip:If you specify the same SCA identifier for multiple message events. . Select the output variable that you want to use to for correlation. The business object type that you select determines the output parameters of the intermediate message event. If you want.For undercover agents that are implemented using a complex variable rather than a service. A. click Select to select a business object (BO) type. 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. The message object type must be a complex type.If you selected an existing service definition and the message object type was not set. see Using Service Component Architecture to interact with processes. or select one from the drop-down list of services that match the selected message object type. click the X (delete) icon. or whether it is stored for future delivery. On the Properties tab. For Message Object Type. . - If you use SCA. 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 . For each variable. 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. Map each output variable to a local variable in the BPD. D. 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. Tip: Undercover agents must have a schedule type of On Event to function as a message trigger. click New.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. In the Message Trigger section. Open the Process Designer desktop editor. while message end events have only incoming sequence flows. or a message end event when you want to send a message at an end of a path. . select Sending from the available message types in the drop-down list. For example. then select the same undercover agent for both the receiving intermediate event and the sending message end event in the other BPD. select the new event. Message events can be included in the process flow. all message end events are sending message end events. Open a BPD and drag an intermediate or end event from the palette onto the BPD diagram. complete one of the following actions. . If you are creating an intermediate message event. if the sender of the message is a message end event in another BPD. By default. Important: The sender and receiver of the message must both use the same undercover agent. 4. Procedure 1. If you are creating a message end event. you must be in the IBM® Process Designer desktop editor. 7. In the diagram. you should be aware of the general information in Modeling message events that applies to all types of message events. which is connected with sequence lines. 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 . 3. type a name for the event. 5. The default implementation for intermediate events that are included in the process flow is Message. See Undercover agents. 2.To create an undercover agent. click Implementation. Intermediate message events have both incoming and outgoing sequence flows. select Message end event as the implementation type. In the text box that displays over the event.To select an existing undercover agent. For example. Before you begin To perform this task. Tip: When you add message events in a BPD. 6. click Select next to the Attached Message UCA field. On the Properties tab. Use the Sequence Flow tool to connect the event as needed. 8. Plus. Click the variable selector icon to map each input variable to a local variable in the BPD. If you created an end event. specify the input mapping.information from the event. .Enter a literal value or the name of a local variable. Open the Input section. When you enable this check box.To use the default value from the variable. 9. C. select it then complete one of the following actions. click Use default. . For each variable. the variable selector icon is disabled. B. click Data Mapping. A. 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 . On the Properties tab. Map each input variable to a local variable in the BPD. . 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. You can override the default target by selecting a check box in the implementation settings for the UCA that carries the event. When the check box is selected. 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. To change that default behavior.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. 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 is that they are used on the tip in Process Center and in the default snapshot on IBM® Process Server. 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. 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. 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. 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 .) You encounter the check box when you are configuring the undercover agent for a message event. If you select the check box. you are limiting the responding listener to the start message event and to the intermediate incoming message events in that specific process application snapshot. you can exercise some control over which snapshots use the event. For start message events. (The label depends on your context. In the text box that appears over the event. When you enable this check box. 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. Open a BPD and drag an end event from the palette onto the diagram. See Undercover agents. if the receiver of the message is an message intermediate event in another BPD. message end events can only send messages. By default. Click the Implementation option in the properties. 6. Click the Use default check box if you want to use a default value from the attached undercover agent for a particular variable. Click the drop-down list and select Message from the end event types. click Select next to Attached UCA to select an existing undercover agent. 2. type a name for the event. 7. 3. 5. In the Message Trigger section. then select the same undercover agent for both the sending message end event and the receiving intermediate event in the other BPD.Using message end events You can use a message end event when you want to send a message at an end of a path. Undercover agents must have a schedule type of On Event to function as a message trigger. you should be aware of the general information that applies to all types of message events covered in Modeling message events. 4. Note: Ensure that the sender and receiver of the message both use the same undercover agent. When including message end events in a business process definition (BPD). Procedure 1. the variable selector icon is disabled. 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. click New. Parent topic:Modeling message events 212 . For example. Open the Process Designer desktop editor. In the Input section. About this task For example. Before you begin To perform this task.To create an undercover agent. Click the Data Mapping option in the properties. you might want to send a message to be received by the Start event in another process or processes. Plus. 8. you must be in the IBM® Process Designer desktop editor. . Parent topic:Modeling events Related information: Configuring access to Process Portal action policies Deprecated: Defining ad hoc actions 213 . you can do so by using a start ad hoc event in your BPD. For example. Important: Ad hoc actions are deprecated in version 8.5. you may want to enable end users to cancel an order. or perform some other ad hoc function during the normal processing of an order.5. Modify the security properties of the BPMActionPolicy configuration object as described in Security configuration properties. instead use Creating an unstructured (ad hoc) activity. Because an ad hoc action is run in the context of the regular process instance.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. it has access to all the data of the regular process instance and can also manipulate the flow of the regular process instance.Testing a sample ad hoc action (deprecated) Use IBM® Process Designer to test the sample ad hoc action. determine the status of an order. depending on the logic that you include.0. If you want to enable end users to perform an ad hoc action during the execution of another process.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. .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. 4. 214 . type Ad hoc event . Open the Process Designer desktop editor. In the text box that displays over the user task. 3. Drag a start event from the palette onto the BPD diagram so that it is positioned in the new Ad hoc event lane. Before you begin To perform this task. In the text box that displays over the start event . ask your IBM Business Process Manager administrator to give you access. (If you do not see the Hiring Sample process application in your list of applications in the Process Center Console. 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. connect the Show Requisition Data start event. type Show Data for the user task name. 9. Click the new lane in the diagram (named Untitled 1 by default) and in the Name field in the properties. you must be in the IBM® Process Designer desktop editor. 6. the Show Data activity. If you wanted to restrict the users who can perform the action. type Show Requisition Data for the event name. 8. About this task For the following example. 10. 11.) To do so. Right-click the Show Data activity and select Activity Wizard from the list of options. 13. 12. 7.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. 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). and the end event on the BPD diagram. Drag an activity from the palette into the Ad hoc event lane. clone a snapshot of the Hiring Sample process application so that your changes do not affect other users of IBM Process Designer. Drag a swimlane from the palette to the diagram. 2. 5. Using the Sequence Flow tool. Click the Implementation tab in the Properties view and select Ad Hoc from the available start event types. 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. Procedure 1. you can use the Standard HR Open New Position business process definition (BPD) included in the Hiring Sample process application. Open a BPD in the Designer view and click the Diagram tab.. In the Activity Wizard .Setup Activity window Option Activity Type Service Selection Selection User Task Select the Create a New Service or Process option. 18. name the new Human service the same as the corresponding activity in the BPD.) 15. For other variables. Recommended selections in the Activity Wizard . 19.Setup Activity window. click Next. Save your work and then follow the instructions in Deprecated: Testing a sample ad hoc action. 17. make the following selections: Table 1. The new service includes a single Coach.14.Setup Activity window. The new service is created and attached to the activity.The new service opens and you can see the service diagram. the Coach includes a form element for each of the parameters in the requisition variable. In the Name field. Double-click the Show Data activity in the Ad hoc event lane in the BPD. Parent topic:Enabling users to perform ad hoc actions (deprecated) Related information: Hiring tutorial Configuring access to Process Portal action policies 215 . Click Finish.Parameters window. In the Activity Wizard . choose the process variables from the regular process to use as input and output for the new service for the ad hoc process. These settings reflect the fact that our sample ad hoc event simply displays the requisition data and does not pass back modified data. type Show Data for the new service. (For this example. leave the Input field set to true and change the Output field to false. 16. click to change the setting from true to false under the Input and Output field. Because we used the Activity Wizard.For the private variable named requisition. In the Activity Wizard . Click the Coaches tab and then click the listed Coach to see its controls. you must have a business process definition (BPD) that contains an ad hoc event and at least one task connected by sequence flow. Run the Submit requisition task displayed in your Open Tasks view in IBM Process Portal. 7. 9. 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. Run the Show Data task. 4. 5. to see whether the requisition has been approved. For example. When the next task for the process instance (Approve/reject requisition) displays in your Open Tasks view in IBM Process Portal. Note: If the task does not display. You can invoke the ad hoc action again. IBM Process Designer switches to the Inspector where you should see a new Submit requisition task in the task list. Procedure 1. you can modify the Hiring Sample BPD to contain an ad hoc action as described in Deprecated: Building a sample ad hoc action.Now you can continue with normal processing by completing the next task in the process instance. click Next.Testing a sample ad hoc action (deprecated) Use IBM® Process Designer to test the sample ad hoc action. IBM BPM displays the data that you entered in step 5. (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. Before you can test the sample ad hoc action. If you receive an information message about claiming the new task. after completion of the Approve/reject requisition task. Click OK. you must be in the IBM Process Designer desktop editor. click the instance name or task subject to open the details page. and then Submit on the Confirm Job Position form. reload the browser page. Click the Run icon in the upper right corner of the BPD diagram. 10. Open the Process Designer desktop editor. 3. 6. Open a BPD in the Designer view. click Claim Task. 11. 2. Fill out the Job Requisition information. If you are using the modified Hiring Sample. )IBM BPM generates a new task called Show Data. 8. Parent topic:Enabling users to perform ad hoc actions (deprecated) 216 . the name is Show Requisition Data. which is displayed in your Open Tasks view. Approve/reject requisition. 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. and select the name of the ad hoc action. Before you begin To perform this task. Click the Actions menu in the toolbar. Related information: Getting started with Process Portal Configuring access to Process Portal action policies 217 . and you can add as many as you require.Intermediate timer event When creating an event gateway. In the Behavior section of the general properties. Before you begin To perform this task.Intermediate message event (receiving) . when connected to an event gateway. Procedure 1. 3. IBM Process Designer automatically adds an intermediate message event (receiving) and an intermediate timer event to the process diagram. The minimum number of events is two. In the text box that displays over the gateway. To streamline configuration of an event gateway. To configure an intermediate message event. 6. The event gateway represents a single point of behavior that is spread out across multiple process components connected by sequence flow. follow the steps in Modeling timer events. These intermediate events are grouped with the event gateway in the process diagram. 7. Drag a gateway from the palette to the process diagram. Only intermediate message events and intermediate timer events are allowed. type a name for the gateway. 2. About this task An event gateway represents a branching point in a process execution where only one of several paths can be followed. B. such as the receipt of a message or timer event. Open the Process Designer desktop editor. Add any additional events required by the gateway configuration by dragging them from the palette to the event gateway group in the process diagram. 4.Modeling event gateways Use an event gateway to model a point in the process execution where only one of several paths can be followed. The following types of events can directly follow an event gateway (connected by a single sequence flow): . A specific event. determines the path that will be taken. A. 8. Click the General option in the properties. 218 . Open a business process definition (BPD). And. click the drop-down list and select Event Gateway from the available gateway types. Click an event in the group and then select the Implementation option in the properties. To configure an intermediate timer event. follow the steps in Using intermediate and boundary message events to receive messages. an intermediate event is not allowed to have additional incoming sequence flow. you must be in the IBM® Process Designer desktop editor. depending on events that occur. 5. you must connect at least two intermediate events to the gateway. depending on events that occur. Parent topic:Modeling events 219 . if a BPD involves filling orders.Filter the specific errors that are caught by selecting an error code from a list of all thrown errors for the linked process. map the error data. From the BPD diagram or a service diagram in Process Designer. . Under Implementation. The error intermediate events are boundary events. To catch specific errors. select an error code from a list of previously defined errors and map the error data to a variable. . To catch errors using error intermediate events. or service. a subprocess. In the subprocess. Error handling that you build into the BPD could create notifications to replenish items that are out of stock. provide logic to recover from possible errors that might be generated in the runtime application.To detect errors. which are intermediate events that are attached to the boundary of an activity. 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. Each boundary event can be triggered only while the activity is running. When building services. For example. designate the error behavior for the events on the Properties tab in your diagram.Error intermediate events in BPDs and services that catch errors . or both.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. as described in the following bullets. you can attach an error intermediate event to the boundary of a step to catch all errors for the step. you use an error start event that catches errors if the start event is triggered. you can select the error code.To recover in a predictable manner. If there are multiple error events defined to catch errors for an error that is thrown in 220 . go to the Error Properties section to designate the following error handling behavior: . subprocess.Map the error data into a variable by selecting an error mapping variable that was previously defined on the Variables tab. build error handling into BPDs and services to do the following things: . However you decide to catch errors. When you develop an application in IBM® BPM. There are three types of error events: . Important: If the error code has changed. or a service. You also can catch errors using error event subprocesses in BPDs. Another way to catch errors is by using error intermediate events in services that catch all errors. 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.Error end events in BPDs and services that throw errors . . interrupting the activity. make sure to select the variable again so that it is mapped properly. .Handling errors using error events When you design a business process definition (BPD) or a service. which causes an error.To specify how errors are thrown and caught in your runtime environment.Catch all errors or specific errors. an item might be out of stock during one instance of the BPD. a linked process. Errors are caught in the following order in your runtime environment: 1. and you can use error end events to throw errors. Table 1.5. and a subprocess is in a BPD or in an unattached intermediate error event in a service. If there is no error event subprocess that handles the error in an event subprocess. or service. and you can throw errors using error end events. 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. If the type of the variable and the type of the error data that is displayed on the Properties tab do not match. subprocess.Handling errors in services For services. linked process. Parent topic:Modeling events 221 . errors are propagated to the next level. Specifying the variable name in the mapping controls the filtering by error data type. the variable type determines the behavior. as specified by the preceding rule Errors with the same data type.x and earlier If you have Process Designer models from V7. 2. as specified by the preceding rules All errors that are not already caught by an event. the catching event is determined by the precedence rules in the order that they are listed in the Error event components table. you can catch errors using error intermediate events or event subprocesses. 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. errors are caught in the error event subprocesses. . .x or earlier that use error events. The boundary events catch errors that are raised by the attached activity. you can use error intermediate events to catch errors. 3.Error events in models from V7. the earlier error handling behavior is still available. unless they are already caught by an event.5.Handling errors in BPDs When modeling error handling as part of your business process definitions (BPDs). If there is no error boundary event that handles the error. or service. . unless they are already caught by an event. as described in the following table. as described in the following table. 222 . and mapping to a variable after the errors are caught. .Define a readable process by locating the error event in the event subprocess instead of defining it in the process. filtering on the error code for the types of errors that are caught.system. Table 1. or event subprocess that directly contains the error event subprocess Throws an error error end event Catching errors using error intermediate events For BPDs. consider the following points: . You can use error event subprocesses to handle errors in your BPD.Handling errors in BPDs When modeling error handling as part of your business process definitions (BPDs). To determine whether to use error immediate events.If an error occurs while a process is running an activity with an attached error event at the boundary.error variable. .step. The event subprocess is not connected by sequence flow and runs only if the start event in the event subprocess is triggered. subprocess.You can have multiple error events for an activity. 223 . but only one catches the error. or if only an error code is specified. When all errors are caught. To determine whether to use error event subprocesses. 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.Error intermediate events must be attached to an activity. consider the following points: . you can catch errors using error intermediate events or event subprocesses. you can attach an error intermediate event to an activity and connect that event to an error handling flow or activity. and you can throw errors using error end events. An error event subprocess is an event subprocess that contains an error start event. . the process flows along the sequence line that is attached to the error event. the error data is captured in an XMLElement in the tw.Consider specifying the error data to catch specific errors. 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. Errors are handled in the flow and then proceed with the normal processing. The attached error event is known as a error boundary event. it might be more efficient and readable if subprocess can be reused. If a correction is not possible at the lowest level of the implementation. When working with either error events or event subprocesses. you must attach an intermediate event for each of the tasks and then connect those events to the error-handling flow. You can define only those data objects that belong to a subprocess. to ensure that any errors that might occur during process run time are captured. or if another error can be thrown at another level.Define data objects that you can access only from within the event subprocess. In other cases. think about whether errors can be handled immediately. 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. use event subprocesses. Build each linked process and service so that errors can be captured and corrected. To reuse an error-handling flow using attached events. . see Modeling event subprocesses .To reuse the error-handling flow for multiple tasks in your process. For example.. For more information about event subprocesses. Parent topic:Handling errors using error events 224 . as shown in the following section. 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. The parent process is not cluttered with unnecessary variables. and normal processing can continue. Then implement error handling from the bottom up. 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. You might. Table 1. It is recommended that you not wire back into the normal flow. or if only an error code is specified. and you can use error end events to throw errors. logic should be concluded with an end event. When all errors are caught.You must attach error intermediate events to steps in your service.Include error intermediate events in the service flow so that they can act as global error handlers in the service. after the error handling. An error intermediate event in the service flow can act as a global error handler in the service.Handling errors in services For services. and normal processing can be continue. Using error intermediate events in the service flow The use of error intermediate events in a service flow offers several options in error handling. You can specify an error code and error data for the error. you can use error intermediate events to catch errors. . or if another error can be thrown at another level. 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. it is a catchAll error event. . It catches errors that are not already handled by boundary error events. This event can have only outbound links. The attached error event is known as a error boundary event. but it must be done carefully to prevent unexpected behaviour. 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. the error data is captured in an XMLElement in the tw. For example.system. Then implement error handling from the bottom up. Throws an error and ends the processing of this service. The error intermediate event cannot catch specific errors. To determine whether to use error events in your services. . for example. use an error end event when you want a particular result from a Coach to end a human service. It is meant for handling errors that can be handled within that very service flow. . consider the following points: . Instead.Use an error end event to throw a specific error.Determine whether errors can be handled immediately.Consider specifying the error data to catch specific errors. After the error handling you 225 .error variable. might reenter the service and run the normal flow with corrected data.insert if not already present --> </server> <!-. add the following entry to the 100Custom.insert if not already present --> <prevent-intermediate-error-loop merge="replace">false</prevent-intermediate-error-loop> </execution-context> <!-.xml file: <server> <!-. Change this property only if all your models are free of endless error loops. Parent topic:Handling errors using error events 226 .insert if not already present --> <execution-context> <!-. use one or more error boundary events with specific errors and the catchAll options. Important: The error intermediate event can cause endless loops if follow-up activities after the event throw a runtime or a modeled error. To allow looping. it might be useful to model a loop with an intermediate error end event.insert if not already present --> Changing this property will globally suppress the error loop detection of the service engine. Note: An error intermediate event in the service flow also catches errors thrown through error end events of that service flow. In some cases. To handle errors in a service and wire back to the normal flow in the same service. The service engine prevents these loops. To use the latest error-handling capabilities.Error intermediate events in the flow of a BPD. delete the old event and add a new event. As of V8. click a toolkit. you can refine your error handling by catching specific errors using the Catch Specific Errors option. . subprocesses.5.Error events in models from V7. Models that were created in V7. or event subprocess catch all errors. You can delete these events.Error end events in services.5. To use the extended error-handling capabilities. In addition.0. or event subprocesses retain the same error throwing behavior: they can be caught only as part of an event that catches all errors.x and earlier If you have Process Designer models from V7. or event subprocess were allowed but had no effect on runtime 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). you can move the models to V8. which is available on the Properties tab for a catching error event. the earlier error handling behavior is still available. Parent topic:Handling errors using error events 227 .0.x and earlier versions include the following errorhandling behavior: . . and select the menu option to upgrade it. you model this behavior using the Catch All Errors option.5. Open your application. subprocess. subprocess.x or earlier that use error events. BPDs. look at the referenced system toolkits. A boundary message event is an intermediate message event that is attached to an activity. You can also use SCA to create a BPD instance without the use of a receiving message event. . You can use receiving message events to create or interact with BPD instances. . the start event that receives the start message is selected arbitrarily. To interact with receiving message events. this event type can be configured to be repeatable or to interrupt the activity that the event is attached to.The start event causes a new instance of the BPD to be created. These interactions are one-way interactions. .Intermediate Message Event .Boundary Message Event . this event type can be configured to be repeatable or to interrupt the parent process instance.The Start Event of a Message Event Subprocess requires correlation. correlation that is supported by undercover agent invocations permits multiple instances and events (of the same or different models) to receive the same message. intermediate message event. 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. if multiple start events specify the same SCA service identifier. the inputs of the BPD and optionally its outputs define the service interface for the SCA interaction. By contrast. 228 . In that scenario.Message Start Event . Optionally. . you can use SCA as the triggering mechanism as an alternative to using undercover agents (UCA). If your BPD includes more than one start event.An intermediate message event requires correlation to ensure that the message triggers the intermediate message event that belongs to the correct BPD instance. or the start event of an event subprocess. A boundary message event requires correlation to ensure that the message triggers the boundary message event that belongs to the correct BPD instance. A receiving message event can be a start message event. Supported interaction patterns that use receiving message events You can use SCA messages to invoke the following BPD event types. Optionally.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). each one should use a different SCA service identifier. Otherwise. A message that invokes a message event subprocess must be correlated with the BPD instance that then invokes the event subprocess.Start Event of a Message Event Subprocess . boundary message event. The SCA response message is constructed from the output variables when the BPD instance ends. The message parameters are automatically assigned to the input variables when the BPD instance receives the SCA message. They are used to store the parameter data of the request message and the response message that are exchanged by means of SCA. you receive a response message that uses the request/response interface of the BPD. Normally. and can never trigger a receiving message event. the correlation variable might be assigned an employee number from the start message. If a message is posted before the a suitable message receive event is in a waiting state. 229 . Both interfaces are available in IBM® Integration Designer for use as an SCA module.You create a BPD instance using the one-way interface of the BPD. For example. The request message parameters are automatically assigned to the input variables when the BPD instance receives the SCA request message. the corresponding service interfaces of the BPD are derived from the message event's service identifier and message object type. business data is assigned to a process instance identifier variable. Because the correlation matching is only performed when the message arrives. it can never match with a process instance. The message will be received by the first matching message receive event that goes into the waiting state.One-way interface . Instance-based correlation If a request message must be received by an existing instance of a BPD.Important: You must ensure that the process instance identifier variable is initialized before any message is sent for the instance. The correlation variable can be written to only once. The value that is assigned to the correlation variable must uniquely identify the instance. Defining a service that can trigger different events in a BPD In general. you must specify a correlation variable to identify the intended instance that receives the message.You create a BPD instance and upon the completion of the BPD. . or the instance is deleted. SCA message correlation requires that at least one of the BPD's variables is marked as being a process instance identifier. The one-way interface and the two-way interface are derived from the input and output variables.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.Request-response interface . There are two interaction patterns: . the message is stored. 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. if a message arrives before the process instance identifier variable is initialized. All messages that are intended for the same instance must include the same value for the correlation variable to identify the appropriate process instance. when receiving message events are used with SCA. . When a message is received. a new instance of the BPD is created. Warning: It is possible to define unintentionally the same service interface for multiple events. The rules are described in Strategies for migrating instances. Rules for instance migration To allow instance migration of BPDs that contain SCA message events and variables that are marked as process instance identifiers. . If SCA messages interact with existing BPD instances. boundary. If this naming conflict happens.If the instance does not have any matching event in the waiting state. 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 example. or a start event for an event subprocess) that is in the waiting state. you can break the naming conflict by renaming the duplicate event names and then restoring the default service identifier name.You can specify that the BPD exposes only one service. intermediate receiving message events. To do so.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. and if so. one of them is selected arbitrarily to receive the message. or if different service identifiers map onto identical NMToken strings. or boundary message events. and the start message event receives the message. or reached first. one of the receiving message events will process it.If the instance has multiple matching events that are in the waiting state. use instance-based correlation for the message event subprocess. 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. Which event receives the message depends on whether a correlating process instance is found.If the instance has exactly one matching event (intermediate. . for the latter you must specify the corresponding receiving message events. Ensure that the process variable that identifies a BPD instance is assigned a suitable value. the matching event receives the message. which is implemented by different receiving message events of the BPD. which event is active.If a process instance matches the instance identifier value in the message. then different events share the same service interface. you must complete the following actions: 1. For that. The value must be assigned before any SCA message can 230 . you must mark one or more of the process variables as process instance identifiers. if different events have identical names (which is shown as an error on the General tab). See Declaring variables for a BPD or a service in Process Designer. specify the same service identifier and message object type for different message events in the BPD. then the following rules are applied: . Task overview To use SCA to interact with a BPD. For the former you do not have to do anything. A. B. the message is stored until an event that can receive the message becomes active. In the assembly editor. 2. Add intermediate receiving message events and boundary message events as necessary. and select which interfaces to include in the SCA import. See Mapping input and output data for an activity or step. B. If you want message event subprocesses or receiving message events in a process to be able to receive SCA messages: 1. Optional: Add a start message event to your process.arrive for the instance. Parent topic:Modeling events 231 . as a part of the data mapping. D. For each receiving message event. and complete the following actions: A. with a corresponding start message event where required. Add a message event subprocess. See Using start message events. See Creating an import to start a business process definition. 2. Drag the BPD onto the design canvas. Switch to using IBM Integration Designer. you can use the SCA import to invoke and communicate with a BPD instance using SCA messages. See Using intermediate and boundary message events to receive messages. See Using start message events. select the variable that uniquely identifies each process instance. C. 3. 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. An undercover agent is started by an event. an undercover agent is needed to trigger the message event in the BPD in response to the message. It is conceptually similar to a message undercover agent. you might have errors that prevent the BPD from starting. 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. you must create and configure a content undercover agent that works with your event subscription. . .messages that you post to the JMS listener (see Posting a message to IBM Business Process Manager Event Manager) When an undercover agent runs. and check the TeamworksConfiguration.BPDs (see Modeling message events) . it starts an IBM® Business Process Manager service or a BPD in response to the event.web services that you create (see Publishing IBM Business Process Manager web services) . For example. A content undercover agent (UCA) is used to initiate a BPM Start or Intermediate event when specific content changes occur on an ECM server.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. If you want to run the startBpdWithName application programming interface (API) to start a BPD instance inside an undercover agent. Message events can originate from any of the following components: . The property is set to false by default.running.xml file to ensure that the setting has the appropriate value. when a message event is received from an external system.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.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. . and if you don't change it. you must attach an undercover agent to the event. Parent topic:Modeling events Related information: Creating inbound integrations Creating an undercover agent 232 . but it has a specialized Content marker to differentiate it from a Message marker.xml file or another override file. set the <enable-start-bpdfrom-uca> property to true in the 100Custom. When you include a message event or a content event in a BPD. For example. Restart the product. Attaching the undercover agent to the message event 233 . In the Common section. three synchronous queues are available.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. Forces one job to finish before the next job can start.Schedule Type: Select On Event from the drop-down list. 6. Open the Process Designer desktop editor. you can type a description of the undercover agent in the Documentation text box. click the drop-down list next to Queue Name to select the queue that you want from the following options: Table 1. Beside the Event Marker area. Available queue options Option Async Queue SYNC_QUEUE_1 SYNC_QUEUE_2 Description Allows Event Manager jobs to run at the same time. or web services that you have created. you can later click Select and then select Content. Before you begin To perform this task. enter the following information: . 5. By default.) 7.Name: Type a name for the new undercover agent. you can see the type of schedule for the current undercover agent in the Schedule Type field. By default. . In the New Undercover Agent window. 3. 2. In the Designer view. (The Content selection is used to work with content events that originate from ECM servers. Forces one job to finish before the next job can start. 4. About this task See Building a sample inbound integration to learn how to build a sample integration that includes this type of undercover agent. the Message selection is used to work with message events that originate from business process definitions. Procedure 1. you must be in the IBM® Process Designer desktop editor. If you want. JMS listeners. Under Details. By comparison. three synchronous queues are available. click the plus (+) sign next to Implementation and then select Undercover Agent from the list. . In the Scheduler section. accept the default event marker Message.Click Finish. 234 . the queue that you select must exist in that environment in order for the undercover agent to run. (The Event Manager monitor might show that the Event Manager has run the undercover agent. Beside the Implementation area. monitoring those jobs. you can click Select to choose a different existing variable type or you can click New to create a new variable type. Ensure that the Enabled check box is selected. If you are using a web service to enable an external application to call into IBM BPM. accept the default selection Variable or select Service (if necessary). However. use a service implementation to process information about events by adding business logic or decisions. and creating and maintaining Event Manager execution queues. When you install and run the process on a Process Server in a test or production environment. if you want a particular process to start when a new customer record is created in an external system. For example. 13. 14. see Maintaining and monitoring IBM Business Process Manager Event Manager. If you selected Variable. select the Use Default check box if you want to use the default value of the input variable in the attached service.) 12. By default. you can associate the start event in the BPD with an undercover agent that handles that incoming 235 . IBM BPM seamlessly uses this ID if you create an inbound integration as described in Building a sample inbound integration. If the input variable of the attached service does not have a default value. Note: For more information about Event Manager jobs. If you selected Service. Use a variable implementation to pass events directly from the undercover agent to the business process definition (BPD). 9.SYNC_QUEUE_3 Forces one job to finish before the next job can start. you can click Select to choose a different existing service or you can click New to create a new general system service. Open the BPD that includes the message event to which you want to attach the undercover agent. the required values are included in the incoming message event and no action is required here.Note: If this check box is not selected. However. If you are posting a message to IBM BPM Event Manager from an external system. the default attached service Default BPD Event is already selected. This ID represents the event message for IBM BPM processing. In the Event section. but if this check box is not selected. you should not alter this ID. In the Parameter Mapping section. 10. By comparison. In most cases. 11.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. the ID in this field is the event name that you need to include in the XML message. three synchronous queues are available. the default variable type NameValuePair is already selected. this check box is disabled. IBM BPM provides a default ID that is unique in the Event Message field. you might use a constant for testing purposes. See Posting a message to IBM Business Process Manager Event Manager for more information about the message structure. the execution does not occur. 8. the Event Manager does not run the undercover agent when the message is received or sent. consider using durable subscription events. Tip: If you occasionally use inbound messages. even if you select the check box to make them consumable.event. In the undercover agent editor. 15. 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. For example. 18. Click the Implementation option in the properties. In the Message Trigger section. Periodically use the BPMDeleteDurableMessages command for deleting durable subscription events. 17. click Select next to Attached UCA and pick the undercover agent created in the previous steps. 19. Click Save and switch back to the undercover agent editor. Durable subscriptions are Java Message Service (JMS) subscriptions that persist and store subscribed messages even when the client is not connected.Note: Ensure that the sender and receiver of a message both use the same undercover agent. if the sender of a message is a message end event in another BPD. Click the message event in the BPD to select it. then select the same undercover agent for both the receiving start event and the sending message end event in the other BPD. 16. Parent topic:Undercover agents Related information: Attaching the undercover agent to the message event BPMDeleteDurableMessages command 236 . The durable messages accumulate. you can see the type of schedule for the current undercover agent. and you want to ensure that the undercover agents run on time. click the drop-down list next to Queue Name to select the queue that you want from the following options: Table 1. three synchronous queues are available. Open a process application in the Designer view. If you are testing a business process definition (BPD) that includes scheduled undercover agents. Forces one job to finish before the next job can start. 7. Procedure 1. . .Name: Type a name for the new undercover agent. you can type a description of the undercover agent in the Documentation text box. 5. In the New Undercover Agent window. Select the plus (+) sign next to Implementation and then select Undercover Agent from the list. Under Details. In the Scheduler section. enter the following information: . you must be in the IBM® Process Designer desktop editor. run the BPD on a Process Server in one of your runtime environments.Click Finish. After you have configured and saved the undercover agent. By default. 4. test or staging environment. About this task Scheduled undercover agents do not run on the Process Center server unless you click Run Now. 6. Forces one job to finish before the next job can start. 3.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. 2. Open the Process Designer desktop editor. Available queue options Option Async Queue SYNC_QUEUE_1 SYNC_QUEUE_2 Description Allows Event Manager jobs to run at the same time.Schedule Type: Select Time Elapsed from the drop-down list. three synchronous queues are available. 237 . Before you begin To perform this task. In the Common section. 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. By default. such as your development. Tuesday. 10. the undercover agent will not run. Note: If you select the First value and also select multiple weekdays.Note: If this check box is not selected. and Thursday. and Thursday. In the Parameter Mapping section. if you select the Last value and also select multiple weekdays. By default. Note: The On the hour value is selected by default in the last column of the Time Schedule section. If the input variable of the attached service does not have a default value.For example.SYNC_QUEUE_3 Forces one job to finish before the next job can start. 238 .Type a value in the text box if you want to manually map a constant value to the input variable of the attached service. and creating and maintaining Event Manager execution queues. Tuesday. If not. Scroll down to the Time Schedule section and use the available options to establish a schedule. press the Ctrl key each time you click an item. 9. and Thursday that occur in the selected months. monitoring those jobs. Similarly. 11. the queue that you select must exist in that environment in order for the undercover agent to run. you might use a constant for testing purposes. clicking the first in the series. the On the hour value will be used even though it is not selected. Note: For more information about Event Manager jobs. Tuesday. If you clear this selection and you do not make any other selection in the column. 8. the undercover agent will run on the first Monday. Ensure that the Enabled check box is selected. Ensure the service shown as the Attached Service is the one that you want to invoke according to the specified schedule. if you select Last and also select Monday. if you select First and also select Monday. the undercover agent will run on the first occurrence of each selected day for the selected months. and then clicking the last in the series. Tuesday. When you install and run the process on a Process Server in a test or production environment. and Thursday that occur in the selected months. the undercover agent will run on the last occurrence of each selected day for the selected months. the undercover agent will run on the last Monday. For example. 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. For example. select the Use Default check box if you want to use the default value of the input variable in the attached service. see Maintaining and monitoring IBM Business Process Manager Event Manager. if you want to start the attached service every weekday at midnight. click Select to choose a different service. this check box is disabled. For example. To select multiple noncontiguous items. three synchronous queues are available. For example. click Select next to Attached UCA and select the undercover agent created in the previous steps. 14. if you want a particular process to start at the same time each day. Parent topic:Undercover agents 239 . 15. Open the BPD that includes the message event to which you want to attach the undercover agent. 13. you can associate the start message event in the BPD with an undercover agent that establishes the required schedule. In the Message Trigger section. Click the Implementation option in the properties.12. Click the message event in the BPD to select it. specify a name for the new undercover agent.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. The New Undercover Agent wizard opens. the Message selection is used to work with message events that originate from BPDs. However. Create a content undercover agent by completing the following steps: A. you must create and configure a content undercover agent that works with your event subscription. B. use a service implementation to process information about events by adding business logic or decisions. C. or web services that you have created.) B. you should follow the instructions in the topic Subscribing to document and folder events: the end-to-end approach. Use a variable implementation to pass events directly from the undercover agent to the business process definition (BPD). In the Schedule Type drop-down list. you can click Select beside 240 . If you need to create a content undercover agent and all of the other required components as well. Configure the content undercover agent by completing the following steps in the undercover agent editor: A. This end-to-end approach is a simpler approach than creating each component on a stand-alone basis. If you accepted Variable as your implementation. accept the default selection Variable or select Service (if necessary). but it has a specialized Content marker to differentiate it from a Message marker. 3. It automatically creates some resources that you would otherwise need to create manually. you must be in the IBM® Process Designer desktop editor. C. Beside the Implementation area. (Use the Content selection to work with content events that originate from ECM servers. In the Name field. By comparison. Beside the Event Marker area. D. The undercover agent opens in the undercover agent editor. D. Open a process application in the Designer view. By comparison. 4. JMS listeners. Before you begin To perform this task. Click Finish. Click the plus (+) icon beside Implementation and then select Undercover Agent. select On Event. the default variable type ECMContentEvent is used and it cannot be changed. Procedure 1. 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. click Select and then select Content. A content undercover agent (UCA) is used to initiate a BPM Start or Intermediate event when specific content changes occur on an ECM server. the default attached service Default ECM Event is already selected. It is conceptually similar to a message undercover agent. 2. Open the Process Designer desktop editor. If you selected Service as your implementation. Parent topic:Undercover agents Parent topic:Performing modeling tasks for inbound events 241 . you might use a constant for testing purposes. this check box is disabled. F. After you have configured and saved the content undercover agent. You can type a value in the field to manually map a constant value to the input variable of the attached service.the Attached Service area and choose a different attached service for the undercover agent. Ensure that the Enabled check box is selected. H. 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. If the input variable of the attached service does not have a default value. Click Save. I. select the Use Default check box if you want to use the default value of the input variable in the attached service. For example. If you accepted the Content event marker and you need to create an event subscription for the undercover agent. G. E. In the Parameter Mapping section. click Add Event Subscription and follow the instructions in the topic Creating and configuring event subscriptions . which enables the content undercover agent to run. Parent topic:Modeling processes 242 . . Enter your text in the Documentation field. paste a link into the Description field of the process application or toolkit. . including hidden formatting characters. Switch to the Overview tab. . Each artifact in IBM® Process Designer has a documentation field for this purpose. .Process documentation location links When you work with process applications and toolkits in IBM Process Center or IBM Process Designer. you might want to capture information about the artifacts that you are creating. Consider the following options: . Open the artifact in Process Designer.Linking to external information To include a link to an external source. 3.Reduce the size of the documentation. See Linking to external information. What to do next Restriction: The documentation field allows a maximum of 200. 2. you can share the location of an artifact in your development flow by copying a link to that artifact.Documenting development artifacts As you develop your process application.Move the documentation content to a separate file and link to or attach the file.000 characters. such as removing tables and text formatting.Simplify the formatting. Long documentation that approaches this limit can impact performance. or the Documentation field of an artifact in IBM Process Designer. Procedure To enter documentation for an artifact: 1. You can enter text or links to external resources such as web sites or attachments. you might need to link to related information that is outside of the IBM Business Process Manager environment. In Process Center. Do either of the following steps: . you might be prompted to log in to the source. . 3. Do either of the following steps: A. When you access a specific content source. or in the Properties editor. the inline editor displays showing you a standard formatting toolbar. The B. you might want to link to a website or a wiki page. complete the following steps: 1. see Using remote assets. For example. click the Insert Link icon on the toolbar and complete the fields in the Add Link window. Log in to IBM Process Center or IBM Process Designer and select a process application or toolkit.In Process Designer. or open the Properties editor.Note: In Process Center. You must log in with a user ID and password that provides access to that content source. In Process Designer. The link source must be registered as a remote content source with Process Center using the Create Registration option. the attachment link type is 243 . Before you begin To add a link in the documentation field in IBM Process Designer. you must use the Process Designer desktop editor. When you work with process applications or toolkits. click the Manage tab. paste a link into the Description field of the process application or toolkit. or the Documentation field of an artifact in IBM® Process Designer. click inside the Description field. To add a link. 2.In Process Center. In Process Designer. You can also reference a change request stored in a change management system or a test case in a quality management system. 4. 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. Procedure To add a link to an external source. a rich text editor window opens that shows a standard formatting toolbar. click the Documentation Edit link in the Common Section of the Overview. 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. For more information about registering a remote content source.Linking to external information To include a link to an external source. Parent topic:Documenting development artifacts Adding a link You can add a link to an external resource in a process application or toolkit description. In Process Center. Table 1. When you create a new snapshot. When you edit an existing snapshot. The asset types are determined by the type of content source that you are using in your project. Also. you can create the attachment link either to an existing design file. or to a new file.available only when you create a new snapshot. Optional: You can specify the relationship type of the link and the asset type that the link is associated to. When you select a link type. when you create an attachment link to a new file: . 5. The link displays as a defect. the description of the artifact is modified with an option that defines the link as implementing a defect. you can create the attachment link only to an existing design file. or edit an existing snapshot. For example.The accumulated total file size for a process application must be less than 600 megabytes. .The files that you add must be 100 MB or less. it can be modified by any asset type that you select. The following table identifies the default link and asset types. 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 . if you select Implements as the relationship type and Defect as the asset type. .The name of the file that you add must be less than 64 alphanumeric characters. 245 . 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. click inside the Description field. 2. . complete the following steps: 1. In Process Center. Do either of the following steps: .In Process Center. Log in to Process Center or Process Designer and select a process application or toolkit. You can now edit the link or the link name. the inline editor displays showing you a standard formatting toolbar. you might need to update the link or change it to a new link.In Process Designer. In Process Designer. click the Manage tab. Place the cursor on the link and click the link text.In Process Designer. 3. Before you begin To edit a link in IBM Process Designer. 4. or open the Properties editor. Do either of the following steps: . Procedure To edit an existing link. you must use the Process Designer desktop editor.In Process Center. The Edit Link window opens.Editing an existing link When you have your link setup. click Edit in the Overview tab or the Properties editor. a rich text editor window opens that shows a standard formatting toolbar. . Perhaps you might need to share a link to an artifact within another artifact. For example. Parent topic:Documenting development artifacts 246 . such as by sharing a link to a process application in the documentation of another process application.Process documentation location links When you work with process applications and toolkits in IBM® Process Center or IBM Process Designer. such as a business process definition (BPD). You might need to provide a link to an artifact. you can share the location of an artifact in your development flow by copying a link to that artifact. outside of IBM Business Process Manager. you might want to email the Process Center location of a BPD or a process application. you can model an activity that is run by a custom Eclipse RCP or Microsoft .1. Parent topic:Modeling processes 247 . 2. 3.Using external implementations You can create external implementations for activities that are handled by applications outside of IBM® Business Process Manager. external implementations were referred to as external activities.5. Using an external implementation to implement an activity Select a custom application to implement a particular activity (step) in a BPD. To use an external implementation to implement an activity in a business process definition (BPD). Tip: In product releases older than V7.NET application. 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. complete the tasks listed in this section. For example. 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. 1. For example. the Eclipse application. Search using keywords web-api. Parent topic:Using external implementations Next topic:Creating an external implementation Related concepts: Web API and external implementations 248 . is a complete working example of external implementations. 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. It represents one step in a process and can be modeled as an external implementation in IBM Process Designer. If you import the BPD External Implementation Library and other associated components in the ExpenseApproval.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. The sample external implementation is a custom Eclipse application that enables managers to either approve or reject expense reports from their employees. you must use the IBM Business Process Manager Web API to enable your custom application to interact with IBM BPM. Download the samples archive file from Sample Exchange Home. combined with the corresponding library items. The IBM Process Designer enables you to include these custom applications in your Business Process Definitions (BPDs) and model them as external implementations.twx file from the sample. If you want to build a custom application to implement an activity within a process. 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. The Samples Exchange on Blueworks Live includes a sample external implementation. Click the plus sign next to Implementation and select External Implementation from the list of components. optionally provide a description in the Documentation text box. for an external Eclipse RCP application. In the Custom Properties section. these articles are helpful. About this task Using the external implementation function is similar to using the service functions like an integration service or web service. The related links at the bottom of this topic link to more information on the Web APIs and REST APIs. The previous topic discusses a sample that creates an external implementation with the Web APIs. Click Finish. Using the REST APIs in IBM Business Process Manager and Integrating a business process application with an external system using the REST API. 7. To create an external implementation. Open the Process Designer desktop editor. Alternatively. For example. When a step in a business process is implemented with an external implementation. In the Common section of External Implementation. 3. 5. To create an external implementation with the REST APIs. Supply a descriptive name for the new external implementation. 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. If you did not build the custom application. 2.For example. 6. the external implementation is more generic in nature. use the Web APIs or REST APIs. specify the properties to identify and run the external application. you need to coordinate with the developers to ensure that you provide the appropriate properties in IBM Process Designer. Procedure 1. 4.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. you must be in the IBM® Process Designer desktop editor. However. You can create parameters with a special meaning. you need to know the properties to use to identify and run the custom application. the business process halts and waits for input from the external application. Before you begin To perform this task. unlike those service functions that are designed for a specific area like web services or integration. you might use the external application name or system ID to find the implementation. Open a process application in the Designer view. suppose you need to pass a URL address as a custom property? In the Custom Properties 249 . When you create an external implementation in IBM Process Designer. For dynamic data. In the article. You can also use this section to pass data to variables in a client that were instantiated with a constructor. which would be different for each process instance or environment. In the Parameters section. Click Save in the main toolbar.).For example. Load External Activity URLs from Teamworks Portal. add the parameters for the external implementation by clicking Add Input or Add Output. use the Parameter Details section as outlined in the following step.. 9. 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. 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. 8. In the Custom Properties section add the URL for Process Portal as shown earlier. What to do next You can use an external implementation with Process Portal..section you could use url as the name and then add a value that is the URL itself (http://mysite. Note: You can add custom properties to pass static metadata about the implementation to the external application. if the external implementation provides an interface in which a manager can either approve or reject an expense report.com. 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 . Type an optional description. Restriction: Do not use JavaScript variable references in task narratives if you need the data to be available after the task completes. 5. Click the Implementation tab in the properties. Open a BPD and click the activity that you want to implement using a custom application. specify the following properties: Table 1.If the external implementation has not been created. You can also use the IBM Business Process Manager embedded JavaScript syntax (for example. Instead. 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. In the Task Header section. such as a database. Open the Process Designer desktop editor. store the data items in another location.local. 3. Before you begin To perform this task.mySubject#>) to express the subject. You can also use the IBM BPM embedded JavaScript syntax to express the narrative. 4. About this task The following steps describe how to select a custom application as the implementation for an activity in a BPD: Procedure 1. <#=tw. Click the Select button to choose an external implementation from the library. select the User Task or System Task option from the displayed list. Once a task is complete. IBM BPM removes the data for completed tasks to conserve space. 2. 6. you must be in the IBM® Process Designer desktop editor.Using an external implementation to implement an activity Select a custom application to implement a particular activity (step) in a BPD. click the New button and follow the steps in Creating an external implementation to create a new external implementation. 251 . Under Implementation. the Data Mapping tab for the activity in the BPD should include those parameters. and then click the auto-map icon in the upper-right corner of the Output Mapping section. and Holiday Schedule fields set to (use default). Save the implementation.) 12. Normal.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. see Business objects and variables in Process Designer. For example. you can select US/Pacific for users who work in California.Because you added the input and output parameters for the external implementation when you created it. the variable should reflect the value that you want for the time period. Note: You can leave the Schedule. or Very Low. you can enter a value in the text box and then choose Minutes. Each Holiday Schedule is made up of a list of Dates. then IBM BPM assumes that the holiday schedule is filled in appropriately. 13. If you do. seven days a week to be the time period in which the resulting tasks from the current activity can be due. you can use the text box after the drop-down list to include hours and minutes in your specification. Low. If you use a TWHolidaySchedule variable. then IBM BPM looks up the holiday schedule by name according to those rules. click the auto-map icon in the upper-right corner. 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. you can enter either a String (or Stringgenerated JavaScript) or JavaScript that returns a TWHolidaySchedule variable. For the Due In field. Hours. For the Time Zone field. or Days.) You also have the option of using the variable selector next to the text box to choose an existing variable from the library. Be sure to select the option that you want from the drop-down list: Minutes. at run time. Urgent. See Setting the work schedule for a BPD for more information. For more information about mapping variables. select 24x7 if you want 24 hours a day. If you use a String. the work schedule specified for the BPD is used. or Days from the drop-down list. 11. 7. Under Input Mapping. For the Time Period field. Click the Data Mapping tab in the properties. (Go to the System Data toolkit and open the TWHolidaySchedule variable to view its parameters. For the Priority field. Timezone. click the drop-down list to select one of the options. 8. click the drop-down list to select one of the default priority codes: Very Urgent. 10. For example. click the drop-down list to select the time zone that you want to apply to the tasks that result from the current activity. (When you choose Days. 9. Hours. If you choose JavaScript. Parent topic:Using external implementations Previous topic:Creating an external implementation 252 . For the Holiday Schedule field. Agent An external system calls Undercover Agent and into IBM BPM to initiate a Web Service service. update.Web services compatibility Web services conform to a flexible architecture that allows variation in web services implementations. . or an external database. web services. IBM with an external system to Case Manager Integration retrieve.Integrating with web services. Depending on the system that you are integrating with. such as a web service. . and integration services. or Undercover data. You can manage inbound and outbound communication with external systems using undercover agents. or insert data. update. you can implement the integration service using an Integration Service implementation or an IBM Case Manager Integration Service implementation. external applications can call into IBM BPM to initiate services. or insert Service. a content management system. And. you need to build several IBM BPM components and corresponding services. . Supported integration types Integration type Outbound Inbound Description Required IBM BPM components IBM BPM communicates Integration service. This variation unfortunately can lead to compatibility problems. Java and databases You can configure IBM BPM processes to communicate with an external system to retrieve.Creating outbound integrations Outbound integrations enable business process authored in Process Designer to interact with other systems. IBM® Business Process Manager supports both outbound and inbound integration as described in the following table: Table 1. Parent topic:Modeling processes 253 .Creating inbound integrations For inbound integrations that involve an external system or application calling into IBM Business Process Manager to kick off a 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. 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 <soap:header> tag in the <wsdl:input> and <wsdl:output> 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 = "<x:sessionId xmlns:x=\"http://acme.com\">1237314</x:sessionId>"; 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 = "<x:subscriptionId xmlns:x=\"http://acme.com\">123-4567-9012</x:subscriptionId>"; // Initialize the "auditLogUUID" header var header2 = new tw.object.SOAPHeader(); header2.name = "auditLogUUID"; header2.nameSpace = "http://acme.com"; header2.value = "<x:auditLogUUID xmlns:x=\http://acme.com\">ab74-ffce-3333-feab</x:auditLogUUID>"; // Now add the two headers to the SOAPHeaders variable tw.local.requestHeaders.headers[0] = header1; tw.local.requestHeaders.headers[1] = header2; 261 5. On the Data Mapping tab of the Properties view, in the Input Header Mapping section, add your newly created variable (either requestHeader or requestHeaders) to map it to a request SOAP header. 6. Complete the definition of the web service integration. 7. Run the integration service by clicking Run Service and verify that the SOAP headers are added to the request message. Parent topic:Creating implicit SOAP headers for outbound web service integrations Related information: Retrieving SOAP headers from the SOAP response message 262 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. Before you begin This task requires that you have access to an integration service with a web service integration component and a SOAP request message. Procedure 1. Select the web service integration component and click the Variables tab above the diagram area. 2. Create the private variable of the type SOAPHeaders. This variable will receive the header entries from the SOAP response message. 3. On the Data Mapping tab of the Properties view, in the Output Header Mapping section, map your newly created variable to the response SOAP header. When the web service invocation finishes, this variable is initialized for you and it contains all the SOAP header entries from the SOAP response message. 4. To access the headers that have been received by the variable, add JavaScript code to Post-execution Assignments on the Pre & Post tab or add a server script component after the web service integration component and add the code there. The following example shows how to access the header entries. In this example, the private variable tw.local.responseHeaders is defined on the Variables tab and mapped to the response SOAP header on the Data Mapping tab.var myHeader = new tw.object.SOAPHeader(); var numHeaders = tw.local.responseHeaders.headers.listLength(); for (var i = 0; i < numHeaders; i++) { if (tw.local.responseHeaders.headers[i].name == "header1") { myHeader = tw.local.responseHeaders.headers[i]; } } 5. Complete the definition of the web service integration. 6. Run the integration service by clicking Run Service and verify that the SOAP headers are added to the request message and that the expected SOAP headers are retrieved from the response SOAP message. Parent topic:Creating implicit SOAP headers for outbound web service integrations Related information: Adding SOAP headers to a SOAP request message for an outbound web service 263 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. Before you begin To perform this task, you must be in the IBM® Process Designer desktop editor. Also, the policy set and bindings must be configured by a system administrator. About this task The web services server can be configured with policy sets and bindings. Policy sets simplify the configuration of web services by providing reusable configurations. A web services policy set defines a set of configuration properties to be associated with a web service integration or endpoint. A policy set follows the WS-Policy specification. One example of how policy sets can be used is to configure WSSecurity for your web service endpoint or outbound web service integration. WSSecurity provides SOAP message-layer security with the following tokens and elements: - Security tokens: Security tokens contain authentication information that flows with the message. - Signature elements: Digital signature information for all or part of the message verifies that the original request is not modified. - Encryption elements: Messages can be encrypted, either completely or partially, so that only the intended recipient can read it. Procedure 1. Open the Process Designer desktop editor. 2. Open a process application. 3. Select the Servers tab from the Process App Settings editor. You see the Process App Settings editor when you first click Open in Designer from a newly created process application in the Process Center. Alternatively you can select Process App Settings from the drop-down list on the toolbar in Process Designer. 4. Beneath the Servers heading click Add. Beneath the Server Details heading, enter a meaningful name for the server. From the drop-down list in the Type field, select Web Service. Add a meaningful description of the server in the Description field. 264 5. Beneath the Server Locations heading, enter the following information: - Environment Type: The environment of the web service server. Add the server location information (host name, port, context path, whether it is a secure server, repository name, user ID, and password) for each environment type. These environments are described in the IBM Business Process Manager overview. If you do not provide values for these environments, the values from the default environment type are used. - Default: If you do not provide values for the following environment types, default values are used. - Development: The environment where you develop your services. - Test: The environment where you test your services. - Staging: The environment where you deploy your services for pre-production testing. - Production: The environment where your services are deployed for use by your organization. - WSDL URL: The URL of the web service. For example: http://mycorporation.com/webservice/financialstatements?wsdl. You can enter a URL or browse to retrieve a URL. - Select Browse to launch the Registry Explorer. A. Select a registry type from the list and select a registry URL or enter a new one. B. For protected services, click Is Protected and enter a userid and password. Click Next. C. Enter the name of the web service and click Search services. You can include wildcard characters in the name. For a Universal Description Discovery and Integration (UDDI) registry use the percent sign (%) and for a WebSphere Service Registry and Repository (WSRR) registry use an asterisk (*). D. Select a web service, click Next to see the detailed information and then click 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 provide the other information about the WSDL file. You can use text in the fields or text that is wrapped by <# ... #> control characters; that is, as JavaScript code. - Select View to view the WSDL source code of a WSDL file. - Select Discover to verify that the URL is correct. The Discovery Status field shows Successfully Discovered. - Discovery Status: Confirms if you have made a connection to the server and successfully read the WSDL file. - Override Endpoint: If selected, you can override the WSDL URL field using the fields beneath the check box. This selection can be useful if you use different endpoints for development and testing, for example. - Endpoint Address: The URL of the web service you want to use. You can use the same format as the WSDL URL field that you are overriding. - Port: If there are multiple ports that are defined in the WSDL file and there is a specific port for the web service that you want to use, then enter the port name in this field. 265 You can enter text in these fields or text that is wrapped by <# ... #> control characters; that is, as JavaScript code. - Security and Policy: Determines the type of security you use. - Use Basic Security: This selection means either no security or security through a combination of user name and password, digital signatures, and encryption certificates. - Authentication: Specifies the type of authentication. Authentication ensures that the parties in a transaction are who they claim to be. - None: No authentication is required. - HTTP Authentication: User name and password are passed in a header element of a message. - UsernameToken (password in plaintext): The username token passes the user name and password. The password is in text. - UsernameToken (password in digest): The username token passes the user name and password. The password is in digest form, which means it is a hash value. A hash value for a user name and password makes these values more difficult to detect. - Username: The user name that is registered at the server. - Password: The password that is registered at the server. - Client certificate alias: The alias for the client certificate; that is the alias name that identifies where the client certificate is located. - Sign request: Select if you require messages from the client to be signed. - Expect encrypted response: Select if the client expects an encrypted response message. - Server certificate alias: The alias for the server certificate; that is the alias name that identifies where the server certificate is located. - Encrypt request: Select if you require the request message to be encrypted. - Expect signed response: Select if you want to verify a signed response message from the server. - Use Policy Set: This selection means that a policy set is used to define the configuration and security requirements for the web service. - Policy Set: Specifies the name of the application policy set. Click Select to choose the policy set. The list that 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 more application policy sets in the WebSphere Application Server Administrative Console. Deselecting a policy set also removes the policy binding. - 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 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 more policy set bindings in the WebSphere Application Server Administrative Console. Deselecting removes the policy binding. 6. Save your work. From the menu, select File > 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. <wsdl:operation name="multiCFault"> <wsdl:input message="tns:multiCFaultRequestMsg" name="multiCFaultRequest"/> <wsdl:output message="tns:multiCFaultResponseMsg" name="multiCFaultResponse"/> <wsdl:fault message="tns:multiCFault_multiCFaultFault1Msg" name="multiCFaultFault1"/> <wsdl:fault message="tns:multiCFault_multiCFaultFault2Msg" name="multiCFaultFault2"/> </wsdl:operation> 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: <# out = new tw.object.Record(); out.setSOAPElementNS("http://www.lombardisoftware.com/schemas/ NameUpdateRequest"); out.setSOAPElementName("NameUpdateRequest"); out.defineSOAPProperty("First", "http://www.w3.org/2001/ XMLSchema", "string", false, ""); out.defineSOAPProperty("Last", "http://www.w3.org/2001/ XMLSchema", "string", false, ""); out.First = "John"; out.Last = "Smith"; #> This generates the following XML element: <NameUpdateRequest xmlns="http://www.lombardisoftware.com/schemas/ NameUpdateRequest"> <first xmlns="">John</first> <last xmlns="">Smith</last> </NameUpdateRequest> 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 <server> section that you can use to set up message-level encryption for integration services.<server> <webservice-security merge="mergeChildren"> <keystore-file merge="replace">teamworks.jks</keystore-file> <keystore-password-encrypted>password</keystore-password-encrypted> <private-key> <alias>soaprequester</alias> <keyname>soaprequester</keyname> <password-encrypted>password</password-encrypted> </private-key> <private-key> <alias>soapprovider</alias> <keyname>soapprovider</keyname> </private-key> <keystore-type>JKS</keystore-type> <certificate>path to client certificate</certificate> </webservice-security> </server> Table 1. Elements in the <server> section of the default 100Custom.xml file Element name <keystore-file> Description Provide a name for the key store file related to the service requester. 276 Example profile_root/etc/ws- security/dsigsender.jks <keystore-passwordencrypted> <private_key> <alias> <keyname> <password-encrypted> <keystore-type> <certificate> 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 <server> 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: <userino type="com.lombardisoftware.core.UserInfo" description="UserInfo"> <calendarId type="com.lombardisoftware.client.persistence.common.ID" description="calendarId" /> <fullname type="java.lang.String" description="String">tw_author</fullname> <qualifiedName type="java.lang.String" description="String">tw_author</qualifiedName> <sendToAddress type="com.lombardisoftware.core.routing.Address" description="Address"> <name type="java.lang.String" description="String">tw_author</name> <toGroup type="java.lang.Boolean" description="Boolean">false</toGroup> <toUser type="java.lang.Boolean" description="Boolean">true</toUser> 287 lombardisoftware.lang. 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.lang.</sendToAddress> <userData type="java.UserFactory</factoryName> <id type="java.HashMap org.lang.client.client.TWObject 8.Boolean java. 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.String" description="String">tw_author</value> </entry> <userData> <userId type="com.jdom.lang.Boolean" description="Boolean">false</libraryItem> <name type="java.Long java.lang.core.HashMap" description="HashMap"> <entry key="Full Name" description="Map Entry"> <key type="java.persistence.Calendar java.ArrayList java.lang. Types of objects returned by the Java method if Translate JavaBeans is not enabled Object types java.persistence. Table 1.Boolean" description="Boolean">false</exportable> <factoryName type="java.lang.String" description="String">LSW_USR_XREF</tableName> </type> </userId> <username type="java. If you do not enable the Translate JavaBeans check box.lang.lang.BigDecimal" description="BigDecimal">2</id> <type type="com.lang.lang.String java.lang.lang. 9.String" description="String">com.core.lang.lang.ID$NumericID" description="ID$NumericID"> <id type="java.lombardisoftware.POType$User" description="POType$User"> <deleted type="java. the Java method can only return objects of the types shown in Table 1.lombardisoftware.jdom. 288 .persistence.util.Boolean" description="Boolean">false</deleted> <exportable type="java.Byte java.lang.lang.client.lang.String" description="String">tw_author</username> </userinfo> Note: When you enable the Translate JavaBeans check box.Integer java.math.String" description="String">Full Name</key> <value type="java.common.XMLNodeList and com.Float java.lombardisoftwar e.Double java. the variable type that you select in the Integration service for the value returned from the Java method should be XMLElement or ANY.String" description="String">User</name> <tableName type="java.Integer" description="Integer">2048</id> <libraryItem type="java.Character java.Element com.lang.lang.Document org.common.lang.lombardisoftwar e.lang.Short java. changing. TWObject and TWList classes 289 . Parent topic:Creating outbound integrations Related information: Creating. depending on the requirements of the overall process.10. and deleting a toolkit dependency in the Designer view Building an Integration service Managing external files Using the TWObjectFactory. Nest the Integration service in another service or select it as the implementation for an activity. Check that your system administrator set up the SMTP server. add an input variable with a Boolean value set to true. select the teamworks. 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. 5. you must be in the IBM® Process Designer desktop editor. Create an integration service.Mail class and the sendMessage method that includes the Boolean parameter. Procedure 1. add a Java Integration component. Create all the other variables to pass values to the SMTP server. 2. 4. you can send attachments by using a Simple Mail Transfer Protocol (SMTP) server. including a variable for your attachments.Sending attachments using an SMTP server With a Java Integration component. Before you begin To perform this task. 3. In the Replace Full Paths By File Names field. The input variable instructs the SMTP server to use file names to identify attachments instead of a full path name. In the Data Mapping section. On the Definition tab. In the Integration service. add the variables that are expected by the SMTP server. Open the Process Designer desktop editor. Parent topic:Creating outbound integrations 290 . For example. use a name like useFileName. You must know its URL address when you complete the following procedure. 7. 6. In the Variables tab. Use them later in the Data Mapping section. java:1092) at teamworks. you can use the SQL Integration services available in the IBM® BPM System Data Toolkit.Read existing data from a database . the SQL Integration services enable you to specify certain types of data (like integers. you must be in the IBM Process Designer desktop editor.WSJdbcConnection. for example.Using IBM Business Process Manager SQL Integration services To integrate with an external database. at com.sql. About this task During IBM BPM installation.SQLException: DSRA9350E: Operation Connection. The System Data toolkit includes SQL Integration services to enable you to easily integrate with external databases.SQLConnector.Write new data to a database In addition.ibm. Procedure 291 . including support for parameterized queries.SQLConnector Java class.jdbc.executeMultiple (SQLConnector.Update existing data in a database . When SQL connector services are used in a scenario that requires a global transaction. Important: The SQL connector services in the System Data toolkit support local transactions only. In addition.commit is not allowed during a global transaction.sql. The SQL Integration services enable you to develop implementations to: . 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. Although you cannot alter the SQL Integration services.ws.java:111) at teamworks. BLOBs. Before you begin To perform this task.java:263) The SQL Integration services are Java-based integrations that bind to a specific method in the teamworks. 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.rsadapter.SQLExecutor. when passing data between IBM BPM and a connected database. you might receive an error similar to the following error:java. They do not work properly in global transactions.commit (WSJdbcConnection. and CLOBs).executeInTransaction (SQLExecutor. The SQL Integration services support common database interactions. these services can automatically map query results directly into the relevant variable type. during deployment or in an installation service. 1. 9. Open a process application in the Designer view.Nest a SQL Integration service in another service by dragging it from the library to the diagram of the parent service. double-click the SQL Execute Statement service to open it. 6. 2. Click the indicator next to the System Data toolkit to see its contents. 5.For example. Open the Process Designer desktop editor. Click the Definition option in the properties to display the Java Class and method implemented by the service. click the Java Integration component to select it. 3. 8. Click the indicator next to the Toolkits category to see a list of toolkit dependencies for the current process application. What to do next To use a SQL Integration service in an implementation. . In the service diagram. Click the Implementation category and then double-click one of the listed SQL services. you can: . such as its type and default values (where applicable). Click an Input or Output variable to see its details. 4.Select a SQL Integration service as the implementation for an activity as described in Implementing activities in a BPD . Switch from the diagram view of the service by clicking the Variables tab. 7. Parent topic:Creating outbound integrations 292 . This context information can be anything that you must send along with the web service operation parameters. you need to build several IBM BPM components and corresponding services. You can use the procedures listed in this topic to build and test a complete integration. In an inbound web service integration. 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. you can retrieve SOAP headers from an incoming request message and include SOAP headers in the outgoing response message.Building a sample inbound integration Several components must work together to complete an inbound integration.Creating inbound integrations For inbound integrations that involve an external system or application calling into IBM® Business Process Manager to kick off a service. . Using a SOAP connection. Java and databases Related information: Undercover agents 293 . external applications can call the IBM BPM web service to initiate a particular service or set of services. Parent topic:Integrating with web services. you must use the message structure that is described in this topic.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. An implicit SOAP header is one that is not defined in the web service WSDL document.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. . . .Publishing IBM Business Process Manager web services IBM BPM can publish web services in the same way that it consumes web services. The event waits for the completion of the UCA. . Figure 1. The following image represents the steps required to build a sample inbound integration. .Creating an undercover agent Create an event-based undercover agent. you need to build several components that work together. . To learn how to establish message flow between two BPDs instead of using a service.Building a sample inbound integration Several components must work together to complete an inbound integration. . the event completes.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. Steps to build a sample inbound integration For general and introductory information. References to more detailed descriptions of the implementation options for each component are provided in the relevant sections. see Integrating with web services. . or via JMS as illustrated in this sample. . You can use the procedures listed in this topic to build and test a complete integration.Creating an attached service Create a service to pass parameter values from the message event to the business process definition (BPD).Testing the integration Test the completed inbound integration using the Inspector. When the UCA completes. Note: You can call an undercover agent (UCA) using another business process definition (BPD). using a web service (and an associated caller service). see Using intermediate message events and message end events to send messages and Using message end events. The following sections describe how to create simple components so that you can easily build the integration and also easily test your initial implementation. .Adding a message event to a BPD Start building the sample integration by adding a message event to a business process definition (BPD).Attaching the undercover agent to the message event Attach the undercover agent (UCA) to the message event. To implement an inbound integration in IBM® Business Process Manager. Parent topic:Creating inbound integrations 294 .Creating a caller service Create a service with appropriate inputs to call the undercover agent (UCA) to send the event. Java and databases. you must be in the IBM® Process Designer desktop editor. see Creating a business process definition (BPD) . you can type: Incoming Message Event. type a name for the event. 5. 7. Click the Implementation tab in the properties. 8. Parent topic:Building a sample inbound integration 295 . Drag an Intermediate Event component from the palette onto the BPD diagram so that it falls between the two activities.) 4. Use the Sequence Flow tool to connect the BPD components as shown in the following example: 9. 6. Save your work. Create a simple BPD that contains two activities. For this sample. Open the Process Designer desktop editor. Open a process application in the Designer view. click the drop-down list and choose Receiving from the available message types. The default implementation for intermediate events that are included in the process flow is Message. Before you begin To perform this task. 3. Procedure 1. If not already selected. (If you need detailed instructions. 2.Adding a message event to a BPD Start building the sample integration by adding a message event to a business process definition (BPD). In the text box that displays over the event. 2. 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. Leave the variable type for the output variable set to String. 7. Click the Add Input button and replace Untitled in the Name field with someString. see Building a General System service . (If you need detailed instructions. Open the Process Designer desktop editor. Open a process application that contains a BPD. Because this service is used to simply pass values. 8. Leave the variable type for the input variable set to String. Procedure 1. 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. 6.Creating an attached service Create a service to pass parameter values from the message event to the business process definition (BPD). you do not need to add any service components to the diagram. Create a General System service and name it My UCA Handler or something similar. Parent topic:Building a sample inbound integration 296 . Use the Sequence Flow tool to connect the Start Event and End Event components in the service diagram. 3. Save your work.) 4. Note: For intermediate message events like the one in this sample inbound integration. you must be in the IBM® Process Designer desktop editor. 10. 9. 5. Click the Add Output button and replace Untitled in the Name field with someString. Before you begin To perform this task. even if no parameter values are being passed from the message event to the BPD. Click the Variables tab. Creating an undercover agent Create an event-based undercover agent. This setting is fine for the sample integration. Save your work. you must be in the IBM® Process Designer desktop editor. Before you begin To perform this task. (To learn more about the queue options. Procedure 1. In the Parameter Mapping section.) 6. In the Details section. 5. 4. Open a process application in the Designer view. Open the Process Designer desktop editor. My UCA Handler. you can attach it to the message event. . What to do next Now that the undercover agent is available.Schedule Type: Select On Event from the drop-down list. In New Undercover Agent. About this task The undercover agent tells IBM Business Process Manager what service to run when the message event is received. the queue for processing this undercover agent is set to Async Queue by default. enter the following information and then click the Finish button.Name: Type My UCA or something similar for the name. The message can be triggered by IBM BPM itself or by an external system as in this example. Parent topic:Building a sample inbound integration Related information: Undercover agents 297 . 2. 7. . you can see that the undercover agent is automatically mapped to the someString variable from the attached service. 3. see Undercover agents. Click the plus sign next to Implementation and then select Undercover Agent from the list. click the Select button next to the Attached UCA field and pick My UCA that you created in the preceding steps. 4. which allows you to correlate an event recipient with a particular key. For example. 9. Periodically use the BPMDeleteDurableMessages command for deleting durable subscription events. the message is received. if you have a process application with the instance ID 298 . Click the Implementation option in the properties. Notice that the Output correlation key is automatically set to the someString variable from the UCA. consider using durable subscription events. 3. If not. If there is such a match. the event completes. Open the Process Designer desktop editor.)Tip: If you occasionally use inbound messages. type tw. see Modeling message events. The ability to match the event against the correct instance is called correlation. Open a process application that contains a BPD with a message event. Durable subscriptions are Java Message Service (JMS) subscriptions that persist and store subscribed messages even when the client is not connected.system. Ensure that the Consume Message and Durable Subscription check boxes are enabled. you should go back to the message event in the BPD and attach the UCA as described in the following steps. This sets the value of the someString variable to the ID of the running instance. The event waits for the completion of the UCA. 7. The variable is used as a correlation parameter. you must be in the IBM® Process Designer desktop editor. 5. Procedure 1. In the field next to the variable. Before you begin To perform this task. Note: When an event occurs. (For more information about these options.instanceId. that event must be matched against the correct instance of the process for which the event is destined.Attaching the undercover agent to the message event Attach the undercover agent (UCA) to the message event. which allows you to test the implementation in the Inspector. the message is not received. Click the Data Mapping option in the properties. Click the message event in the BPD to select it. 8. and the event continues to wait. even if you select the check box to make them consumable. The durable messages accumulate. In the Message Trigger section.In this example. 6.process. Open the BPD that includes the message event. 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). About this task After you create the UCA. you are creating a UCA that uses the current process instance ID as the correlation parameter. 2. When the UCA completes. Save your work. only the first process application receives the event. 10.of 50 and another process application with the instance ID of 100. if you invoke the UCA passing an ID of 50. Parent topic:Building a sample inbound integration Related information: Undercover agents 299 . Use the Sequence Flow tool to connect the service components on the diagram.someString. see Building an Integration service. Parent topic:Building a sample inbound integration 300 . 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. 7. (If you need detailed instructions. 9. 12. Before you begin To perform this task. name it My UCA and place it between the Start Event and End Event in the service diagram. Procedure 1. My UCA. Drag an Invoke UCA component from the palette. 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. 2. 6. 13. 3. you must be in the IBM® Process Designer desktop editor. This sets the input value of the UCA to the local value of the someString variable. Click the Variables tab. Click the Invoke UCA component in the diagram. Select the Implementation option in the properties. 5.Creating a caller service Create a service with appropriate inputs to call the undercover agent (UCA) to send the event. Open a process application in the Designer view. Select the Data Mapping option in the properties. Create an Integration service and name it Inbound WS Handler or something similar. 10. type tw. The value is used in the business process definition correlation mapping that is created in the initial task.local. 8. The Input Mapping is automatically set to the someString variable from the UCA. Click the Select button next to the Attached Undercover Agent field and pick the Undercover Agent that you created in the preceding procedure.) 4. 11. which enables you to test the implementation in the Inspector as instructed in Testing the integration. Save your work. In the field next to the variable. Save the changes. and then click the Add Input button to add the someString variable as an input variable. Open the Process Designer desktop editor. The Protected check box adds user name and password security to an operation in the web service. 2. 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. Notice the WSDL URI in the Behavior section. If you want to invoke a web service for a specific snapshot. 6. Select the plus sign next to the Implementation category and then select Web Service from the list. By invoking a SOAP call. it points to the tip snapshot for Process Center. Open a process application in the Designer view. 3. Procedure 1. Before you begin To perform this task. One-way operations are not supported. change Untitled in the Operation Name field to doKick or something similar. All operations that are exposed on an inbound web service are exposed as requestresponse operations. type KickTheBPD in the Name field and then click the Finish button. assigned to the process application and have at least 301 .tws. In the Operations section. you must be in the IBM Process Designer desktop editor. 4. or to the default snapshot for Process Server. the user ID and password added to the user name and password elements for this operation must be registered at the server. make sure to specify the snapshot_name in the endpoint URL. About this task Now you need to provide a way for an external system or application to call into IBM Business Process Manager. For a web service client to invoke a protected operation. Even an operation bound to a service that has no outputs will be exposed as a request-response operation with no output. Open the Process Designer desktop editor. click the Add button and select the Inbound WS Handler Integration service that you created in the preceding procedure from the list. 7. external applications can call the web service. 5. 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. You can use this URI to test the sample integration as instructed in Testing the integration. In New Web Service. If you do not specify the snapshot_name in the endpoint URL.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. In the Operation Detail section. You will not be able to modify or update this value. The list you will see depends on the policies available on the server. You can also create additional application policy sets in the WebSphere Application Server 302 . This scheme was used to define the target namespace before IBM BPM 8. Click Select to choose the policy set. .The Target namespace schema field is changed to the Per snapshot name value. Note that this is not authentication in the context of an HTTP transaction.The inbound web service uses a business object defined in the System Data toolkit.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. . Note that the namespace must be already set at the time of this selection or Per snapshot name will be used. The namespace of the WSDL file will use the snapshot name once you select this option. The server must have been already configured by a system administrator. the namespace of the Web Services Description Language (WSDL) file will be changed in the following cases. and Username WSSecurity default. The target namespace value in your web service client will be different each time a snapshot is taken. WSAddressing default.Custom: Lets you create your own target namespace in the Target namespace field. 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.Per snapshot name: Includes the snapshot name as well as the namespace from the Advanced XML Settings section of the Process App Settings page. 8. You must generate the types again for your inbound web service each time you create a snapshot.1. You must generate the types again if the inbound web service's host name and port are changed because of this situation. This is the recommended setting as the target namespace will remain consistent when using multiple snapshots. The Security and Policy section allows you to configure a policy set and a policy binding with your web service. You will not be able to modify or update this value. . if set. Important: If you select Per snapshot name.Policy Set: Specifies the name of the application policy set.The Target namespace schema field is changed to the Per snapshot name value. the namespace of this WSDL file will not be changed when you switch the snapshot to the default or the non-default version. The namespace of the WSDL file will use the snapshot name once you select this option. The Target namespace scheme drop-down list provides options for setting the target namespace: . . You must generate the types again for your inbound web service so that your namespace is consistent with the namespace on the server.0. Note: In this situation. . The namespace of that business object uses a host name and port specification. .read authority. Some default application policy sets include: WSHTTPS default. so selecting Protected does not display a default user ID and password. if the inbound web service is defined in the toolkit. if you have your web service on a tip in a non-default track. More information on policy sets can be found in the IBM Redbook WebSphere Application Server Web Services Guide. You can also create additional policy set bindings in the WebSphere Application Server Administrative Console. create a snapshot name or make the track that you are working with the default track.system. Click Select to choose the policy binding. Deselecting removes the policy binding. 9. which contains system-specific configuration parameters like username and password information. Parent topic:Building a sample inbound integration Related information: Supported web service standards 303 . You can also write JavaScript code which adds SOAP header entries to the tw. What to do next If you do not specify a snapshot name in the URI.Policy Binding: Specifies the name of the general provider policy set binding.response system variable. Save your work.soap. The tw. The list you will see depends on the general provider policy set bindings available on the server.header. Default policy set bindings include: Provider sample and Provider sample V2. The SOAP header entries contained in this variable are added to the outbound response message. You can include JavaScript code with your inbound web service which accesses these SOAP header entries.request variable is automatically initialized to contain the list of SOAP header entries found in the incoming request message. it cannot be found. However. Deselecting a policy set also removes the policy binding.soap. Therefore.Limitation: Any variable with a simple type containing a restriction element will not have the restriction element on generation of the inbound web service. . then the default track is used to locate your web service.system. The tip in the default track is assumed to contain the process application with your web service.Administrative Console. Note: SOAP header information is available in system variables.header. Testing the integration Test the completed inbound integration using the Inspector. If not. When IBM Business Process Manager prompts you to change to the Inspector interface. in the preceding image. the message intermediate start event continues to wait until a match is found. 304 . In the someString parameter for the method. You should see that Step 2 has been received. Before you begin To perform this task. From the Process Instances tab. meaning that the message event was successfully processed and the instance is able to move to the next step. Click the Done button in the Coach to complete the first step. Click the Refresh icon in the Inspector toolbar. In your SOAP utility. Open a process application that contains the simple BPD that you created per the instructions in Adding a message event to a BPD. 9. 6. opens in a browser. Open the Process Designer desktop editor. For example. 2. Click the refresh icon ( ) in the toolbar. point to the WSDL URI for the KickTheBPD inbound web service that you created per the instructions in Creating an inbound web service. see Stepping through a process. 11. the message intermediate start event runs. You can see that the process instance is waiting for the incoming message event. Click the Step 2 task to select it and then click the Run task icon. 7. provide the Instance ID for the currently active instance. click Yes. The value is used in the business process definition correlation mapping that is created in the initial task. initiate a request to the doKick method. About this task After you build and link the input and output of the required components as instructed in the preceding procedures.) 4. If this value and the value of the BPD mapped variable are equal. Note: Click the check box if you want IBM Process Designer to change interfaces without prompting for approval. such as soapUI. 10. The coach for the activity. you can test the completed inbound integration using the Inspector in IBM Process Designer and a utility such as soapUI. Procedure 1. 5. Using your SOAP utility. click the received task for Step 1 and then click the run icon ( ). (If you need detailed instructions for using the Inspector. the instance ID of the active instance is 4. which you can see in the Process Instances tab in the Inspector. you must be in the IBM® Process Designer desktop editor. 8. Open the BPD and click the Run icon in the upper right corner of the BPD diagram. 3. which is the default Human service. 12. 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. The Coach for the activity. opens in a browser. 13. which is the default Human service. Parent topic:Building a sample inbound integration 305 . Click the Done button in the Coach to complete the second step. This context information can be anything that you must send along with the web service operation parameters.soap. .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.system.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. .request system variable.header. you can retrieve SOAP headers from an incoming request message and include SOAP headers in the outgoing response message. Parent topic:Creating inbound integrations 306 . An implicit SOAP header is one that is not defined in the web service WSDL document. In an inbound web service integration.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 you can use to retrieve SOAP headers..soap.system.request system variable.request.soap.header.header.headers[i] } } } if (subscriptionInfoHeader != null) { log.headers[i].request system variable.soap.system.header. the code example is retrieving a header named subscriptionInfo of type SOAPHeader from the system variable tw.system.header.header.request.header.soap.request system variable.name == "subscriptionInfo") { subscriptionInfoHeader = tw. 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.request. You can add a component. log.request != null) { for (var i = 0. you can add the code to any location that is part of the general system service for the endpoint.system. SOAP headers found in inbound request messages are automatically copied to the tw. write JavaScript code that uses the tw. this variable will be initialized to contain them.soap.info("Found the subscriptionInfo SOAP header!") } 307 . Procedure To retrieve SOAP headers from an inbound SOAP request message. If the request message contains SOAP headers. You can write code to retrieve those SOAP headers.. this variable will be null.system. i < tw. i++) { // search for the subscriptionInfo header if (tw.listLength.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. such as a server script component. 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.request. Alternatively. If the request message does not contain SOAP headers.headers.header.soap. to your general system service.header.soap.info(">>>>>> Checking to see if the subscriptionInfo SOAP header was received in the request message.soap.system. In this example.") var subscriptionInfoHeader = null if (tw.system. info("The subscriptionInfo SOAP header was not present in the request message.") } Assume that the following SOAP header is in a request message:<ns1:subscriptionInfo xmlns:ns1="http://acme.com">1234-56-7890-fc3a</ns1:subscriptionInfo> 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 .else { log. response == null) { tw.object. use JavaScript code such as the following example.header.system.soap. add an entry to the SOAPHeaders array within the tw.system.header.value = "<x:sessionToken xmlns:x=\"http://acme.soap. such as a server script component. Follow these best practices as you write your code: ..system.header.com" myResponseHeader.header.header.soap. .info(">>>>>> Adding a SOAP header to the response message.system..soap.soap.SOAPHeaders() tw.system.soap.response variable from the Variables tab above the process diagram or in the JavaScript code. log. as they are in the following examples. .system. You can instantiate the tw.name = "sessionToken" myResponseHeader.response.Avoid white spaces in the XML snippet that constitutes the SOAP header value.SOAPHeader() myResponseHeader.response.Make sure that you only instantiate the tw. tw.headers = new Array() } // Determine which index we need to use when adding the new header entry.soap.nameSpace = "http://acme.header.header. To add a header that is called sessionToken to the response message. // then you must instantiate it if (tw.soap.") // Create the header object var myResponseHeader = new tw.system. you could end up clearing out SOAP header entries that were added by some other component within your general system service.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.response. //Add the new header at the end of the array so that the processing does not // overwrite any existing entries.com\">abdf-128974-33-33-fcea-10243-7433</x:sessionToken>" // If the response header system variable doesn't exist yet.headers.header. var nextIndex = tw. Otherwise.listLength 309 .response variable if it is null.Make sure namespaces are fully qualified.system.response system variable.object. About this task IBM® Business Process Manager provides a system variable that allows you to add SOAP headers to an outbound response message.response = new tw. Procedure To add a SOAP header to an outbound response message. You can add the code to the Pre & Post > Post-execution Assignments section within a component of a general system service. which is an array of SOAP header values.log.headers[nextIndex] = myResponseHeader Note: Use the next available index when adding your new SOAP header entry to the tw.info("Adding new header at index: " + nextIndex) tw.soap.system.response variable "headers" field. Otherwise.header. you might inadvertently clear out an existing SOAP header entry that was added by some other component within your general system service.response.soap. Parent topic:Creating implicit SOAP headers for inbound web service integrations 310 .header.system. See Maintaining and monitoring IBM Business Process Manager Event Manager to learn how the Event Manager processes incoming requests. if you do not include the snapshot name in the message. In addition to user-created complex business objects (variable types). the Event Manager uses the default snapshot on the target Process Server for start message events. you need to wrap the value in a CDATA tag as shown in the preceding example.<parameters> <parameter> <key>param1</key> <value><![CDATA[value1]]> </value> </parameter> </parameters> </eventmsg> If you do not include the snapshot name in the message. all active snapshots receive events. you must assign an undercover agent to it for the message event to run at run time. You can use Java Message Service (JMS) to post a message to the Event Manager. 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. To learn more about active and default snapshots. For more information. which is part of the IBM Process Server. see Undercover agents. For intermediate message events.) The message must be structured as XML as shown in the following example: <eventmsg> <!-. For information about passing parameter values for each complex business object (variable type). (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 process app acronym and event name are required: The snapshot and UCA name are optional --> <event processApp="[acronym]" snapshot="[snapshot_name]" ucaname="[UCA_name]">[event_name]</event> <!--Optional: The name of the queue for the event to run in--> <queue>[queue name]</queue> <!--Any parameters the UCA may require-. Complex business objects that can be used to invoke undercover agents at run time Variable type Record Date and Time Boolean Syntax XMLDocument XMLElement XMLNodeList 311 . The Event Manager.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. Note: If the value of the <value> element contains XML elements or similar content. Passing complex variable types to undercover agents You can use undercover agents to instantiate services and BPDs automatically. see the following section. without human interaction by an IBM BPM participant. handles the scheduling and queuing of undercover agents. see Configuring runtime settings for installed snapshots. When you include a message event in an IBM BPM BPD. the following complex business objects can be used to invoke undercover agents at run time: Table 1. you must use the message structure that is described in this topic. Description. to invoke an undercover agent using an XML message. let's say your runtime process contains a message event that waits for an incoming message.Name: String (John Doe) . The conversion from the event XML format to a complex type is handled automatically by the IBM BPM engine. Then. The element name is case-sensitive. where every object property corresponds to an XML element.Map ANY (default) For example. Passing IBM BPM Structured types All structured objects are passed as XML structures. create the service and then associate the service with an undercover agent (the service describes what happens when the undercover agent is invoked at run time). if the property is Name. send the message with the following syntax: <eventmsg> <event processApp="[acronym]" snapshot="[snapshot_name]" ucaname="[UCA_name]">[event name]</event> <parameters> <parameter> <key>customerParam</key> <value> <Name>John</Name> <Description>John Description</Description> <Age>30</Age> </value> </parameter> </parameters> </eventmsg> The following sections provide examples of how to pass the content of the <value> element.Every object property is mapped to an XML Element with the same name as the property name. The type attribute can be omitted only when IBM BPM knows the exact type or when the type is String. For example: Variable type: Customer .When an array is passed. When the Any type is used to pass a parameter value. the element name must be <Name>. it is mapped as a sequence of XML elements with the same name. . If you pass an attribute (excluding type). . For example. The value of the attribute must be an existing IBM BPM type-or in case of an array. First. For example: <value> <item> <Name>John Doe</Name> <Description>Married</Description> <Age>30</Age> </item> <item> <Name>Jane Doe</Name> <Description>Married</Description> <Age>31</Age> </item> </value> Passing array properties: Every object in the object array is converted to XML using the object property name as an XML Element name. an error is returned because the passed Document is not valid. There are two possibilities: Passing root level arrays: Every object array item must be placed as content of an <item> element. the actual IBM BPM type must be supplied using the type attribute of the corresponding element. For example: <value> <Name>John Doe</Name> <Description>Single</Description> <Age>30</Age> <Address> <Street>10506 Jollyville Rd</Street> <City>Austin</City> </Address> <Address> <Street>10507 Research Blvd</Street> <City>Austin</City> 312 . an IBM BPM type concatenated with the [] string at the end.Description: String (Single) Age: Integer (30) is mapped to: XML: <value> <Name>John Doe</Name> <Description>Single</Description> <Age>30</Age> </value> Keep the following important rules in mind: .All XML element attributes are reserved. This message contains an input parameter whose value includes the Customer Name. not <name>. and Age. because all values are considered of type ANY.<value>2004/03/11 14:02:20. the type does not need to be specified.If an object property is null . and no other modifications (such as adjusting it to the server time zone) is performed. the type information must also be passed (using the type attribute) in order for the correct objects to be instantiated during de-serialization. the type information must also be passed in order for the correct objects to be instantiated during deserialization. the corresponding element is skipped. Example: <value> <![CDATA[ <Customer> <Name>John Doe</Name> <Description>Married</Description> <Age>30</Age> </Customer> ]]> </value> 313 . Passing Boolean type The valid values for the Boolean type are true or false(case is not considered).S z .<value>2000/02/20 11:10:20. Passing Record type The Record type is serialized in the same way as Structured types.0 GMT+6:00</value> When the value is converted to the Calendar Java object. Example: <value>TRUE</value> Passing Map type A Map type is passed to an undercover agent using the following structure: <value> <entry> <key> … </key> <value> … </value> </entry> </value> For example: <value> <entry> <key>TX</key> <value>Texas</value> </entry> <entry> <key>CA</key> <value>California</value> </entry> </value> Because all values and keys in this case need to be of the ANY type. it preserves the time zone. However.0"?> <Customer> <Name>John Doe</Name> <Description>Married</Description> <Age>30</Age> </Customer> ]]> </value> Passing XMLElement type An XML Element is passed as an XML escaped string. If the object is of the String type. Passing Date/Time types The format for passing dates is yyyy/MM/dd HH:mm:ss.</Address> </value> . Example: <value> <![CDATA[ <?xml version="1.0 PST</value> . Example: . Passing XMLDocument type An XML Document is passed as an XML escaped string. Passing XMLNodeList type Every node is passed as an XML escaped string. When the data is encoded in XML. Example: Define a process with one input parameter. The array of the nodes is encoded as a sequence of <item> elements. the actual type must be supplied as the value for the type attribute. of type ANY . Name . the information about the actual type must be passed as part of the XML. the String type is assumed. Example: <value> <item> <![CDATA[ <Customer> <Name>John Doe</Name> <Description>Married</Description> <Age>30</Age> </Customer> ]]> </item>| <item> <![CDATA[ <Customer> <Name>Jane Doe</Name> <Description>Married</Description> <Age>31</Age> </Customer> ]]> </item> </value> Passing ANY type When the type of an input parameter to an undercover agent is declared as ANY . <value type="String"> John Doe </value> Parent topic:Creating inbound integrations 314 . If the type is not passed. click the Add button to choose an existing service to add. Open a process application in the Designer view. You can supply this URI to the developers who need to call the operations within the web service. external applications can call the IBM BPM web service to initiate a particular service or set of services. 9. you can type a description of the operation in the Documentation text box.) 8. See Service components in Process Designer for more information about these components. Before you begin To perform this task. In the Behavior section. 10. Optionally. Select the plus sign next to the Implementation category and then select Web Service from the list. Under Operation Details. a user must supply a user name and password to access the operations described in the WSDL URI. In the Behavior section. Using a SOAP connection. external applications can call the web service. In the New Web Service window. Because the services that IBM BPM initiates from a web service do not have an associated task. 5. click the WSDL URI to view the XML description of the resulting web service and its elements and operations. 2. Open the Process Designer desktop editor. Click the Add button in the Operation section to continue adding services. and Browser Script. enable the Protected check box if you want access to the WSDL URI to be password-protected. Follow these steps to create a web service that external applications can call: Procedure 1. In the Operations section. type a name for the service and then click the Finish button. Using a SOAP integration. type a name for the selected service in the Operation Name text box. 12. 4. you must be in the IBM Process Designer desktop editor. In the Common section. (Change Untitled to the name that you want. 315 . 6. About this task You can create and publish a web service to enable external applications to initiate a particular IBM BPM service or set of services. Include a message event in your BPD for the incoming request as described in Modeling events. Note: See Building a sample inbound integration to learn how to build a sample integration that includes a web service. 11. do not add services that include the following components: Coach. If password-protected. Modify Task. 7. you can type a description of the web service in the Documentation text box.Publishing IBM Business Process Manager web services IBM® BPM can publish web services in the same way that it consumes web services. 3. Parent topic:Creating inbound integrations 316 . What to do next Note: When you install a process application on a test or production server.13. all web services are included in the list of exposed items in the Process Admin Console. Create an undercover agent that calls this web service as described in Undercover agents and then attach the undercover agent to the event from the preceding step. In the topic XML constructs not supported. Note that IBM Business Process Manager Standard has the following restrictions: . that passes simple type parameters.SOAP / JMS: SOAP over JMS is not supported.SOAP faults are not supported.Verifying that the web service is working First check that the web service is working. Tables are provided that list errors and warnings caused by incompatibilities.HTTP headers are not supported. The web service must be working before you can call it from a business process. If you are using IBM Business Process Manager Advanced and experiencing web services difficulties associated with incompatibilities. . which show this approach. and that is to use a SOAP connector. Java and databases 317 .Web services compatibility Web services conform to a flexible architecture that allows variation in web services implementations.SOAP header: There is only support for a request SOAP header that passes complex type parameters. Parent topic:Integrating with web services. you should test it from within Process Designer.The Remote Procedure Call (RPC) binding style is not supported. either request or response. In the following sections. The web services tools in Integration Designer have a variety of popular bindings and features that can be used to handle most web services interactions. These instructions describe testing the web service with soapUI. it is assumed that you have access to a service using Web Services Description Language (WSDL) and that you can make a call to the web service using the soapUI open source tool or another SOAP tool. If you are experiencing problems when you call an external web service from a business process. . Once you know the source of the cause you can correct the web service accordingly. This variation unfortunately can lead to compatibility problems. . you should first check its compatibility with IBM® Business Process Manager. You also have another alternative. . particularly if you have IBM Business Process Manager Standard. .Calling a web service using a SOAP connector When you know the web service works. . There is no support for a SOAP header. these compatibility problems are outlined and explained. consider using an Advanced Integration Service to give you access to Integration Designer. deleting items should not be a problem. Do not change the other values and options and click OK. working URL containing the expected WSDL file. You should now have a sample call for your web service where you can make sample calls based on XML input. For these entries. 2. You can see the following steps with screen captures from a previous version in this technote. If the URL is not working. Paste the URL into a browser window. Paste your WSDL URL into the box labeled Initial WSDL/WADL. 4. you are likely lacking the correct network configuration to access the web service. 6. Right-click Projects and click New soapUI Project. 5. Install soapUI using the default configuration. There are hints that are provided by soapUI in places where repeated entries or optional entries exist. Parent topic:Web services compatibility 318 . The web service must be working before you can call it from a business process. Procedure 1. Verify that you have a live WSDL URL. You may need to add ?WSDL to the end or your URL. 3. About this task These steps let you determine if you have a proper. Test the web service by replacing question marks with actual data inputs and press Play.Verifying that the web service is working First check that the web service is working. 4. you must be in the IBM® Process Designer desktop editor. 8.destinationAddress maps to the soap:address location value. Select the Data Mapping tab in the Properties view.wsdlURL maps to the URL address. 7. In this example. Before you begin To perform this task. Open the Process Designer desktop editor. enter a name and click Finish.serviceName maps to the service name value. . Return to the diagram view and rename the server scriptlet to Set Request. A. The request input includes your variable inputs. Open the variables tab and create a new private variable called request with an XMLElement type. Drag a Server Scriplet from the right-side palette to your diagram. Call WebService via SOAP should connect to End. Select the Call WebService via SOAP component. 9. D. Locate the Call WebService via SOAP component and drag it onto the diagram. Procedure 1. About this task These steps show you how to test your web service. Select the Implementation tab from the Properties view for the server scriptlet and bind the implementation to your request variable. Place it to the left of Call WebService via SOAP. . The Untitled server scriptlet should connect to Call WebService via SOAP. . Click Select and click the request variable from the menu. Click the plus sign next to the Implementation category and select Implementation Service. expand SystemData and select Implementation. 5. 2. Connect the lines. Copy your entire XML input from soapUI and paste it into the server scriptlet implementation. 319 . 6.serviceNS maps to the targetNamespace value. Open a process application in the Designer view.Calling a web service using a SOAP connector When you know the web service works. . Beneath TOOLKITS. B. C. we use the server scriptlet to create the XML input. Start should connect to the Untitled server scriptlet. . You can see the following steps with screen captures from a previous version in this technote. you should test it from within Process Designer. You should be able to identify all of the inputs required except for the request input. 3.soapAction maps to the soap:operation soapAction value. In the dialog that opens. } Parent topic:Web services compatibility 320 .xpath("VisioDocument/Masters/Master[@NameU='Horizontal holder']"). For example: 1. except it ignores namespace and depth of 'Page' node: xml.. using Select. The following example only has one input: A. 3. and bind it to the output of the SOAP Connector. you are ready to add input variables to your service and map them into your request variable in the server scriptlet. Add an input variable to your service. Run the service in debug mode to see the response placed into your response variable.object.E. Return to the Data Mapping section of the Call Web Service via SOAP component and. that is. If it worked correctly.objArray = new tw. Use <#= #> notation to include JavaScript in your server scriptlet.listOf.length.local. In a similar manner.local. The following Xpath expression ignores the depth and ignores namespaces.local.myObj(). Add a Server Script to the end of your service B. This Xpath expression returns a node list of all 'Page' nodes until the VisioDocument/Pages node:xml. for (var i=0.name[0]. Bind your request variable to the request input of the SOAP Connector. you should be able to test your service using hard-coded values.name = nodeList[i]. You might need to experiment with having or not having a slash at the beginning depending on the structure of the XML. Now your service input will determine the input to the SOAP Connector.local. This example uses a single output variable (_degreesC).i++) { var obj = new tw. tw. 2. the implementation code referring to it would be <# = tw.xpath = "//*[local-name()='Page']". the Call Web Service via SOAP component..listLength] = obj.object. tw. 11. For example if your input variable was degreesF. Use Xpath to map the XML response into the output variables.xpath(.getText(). 12.objArray. you need to know the node path and namespace.degreesF #>. //If name node always exists as a child obj. map request (XMLElement) to the request variable you just created.objArray[tw.).xpath("VisioDocument/Pages/Page"). At this point. create a variable called response of type XMLElement. 10. A.myObj(). B.i<nodeList. This Xpath expression returns a node list of all 'Master' nodes that have the NameU attribute equal to 'Horizontal holder': xml. In any case. Use Xpath to map your response variable into proper outputs. It is the same as i. the result is a nodelist that can be used something like: var nodeList = xml. In either case. 321 . . if required. You might also want to consider including cases in your process applications so that they run directly on an IBM BPM process server. see Building process applications.Accessing an IBM Case Manager server using the Secure Sockets Layer (SSL) Some IBM Case Manager servers may use SSL for security protection.Processing a search case operation result A search case operation result is often used with an update case operation.Building the IBM Case Manager Integration service Like other integration services. Since an array is returned in a search case result. Using the auto-map function creates variables. . Specifically. be mapped to the input and output fields. 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. .Building a query for a search case operation A graphical interface helps you build a query to your IBM Case Manager solution. read Copying IBM Case Manager solutions that are associated with IBM Business Process Manager process applications. .Data mapping in case operations Each case operation requires that variables. For more information.Adding an IBM Case Manager server You require at least one IBM Case Manager server to build an IBM Case Manager Integration service. this service integrates with another system.Integrating BPDs with IBM Case Manager cases To integrate with IBM® Case Manager. . this service integrates a business process developed in IBM Process Designer with an IBM Case Manager case management solution. To see the integration from IBM Case Manager to IBM Business Process Manager. you would use JavaScript to iterate through each element of the array and perform multiple updates. . or values in the case of input. Parent topic:Modeling processes 322 . and assigns variables of the right type to each field. Staging: The environment where you deploy your services for pre-production testing. Enter the server location information (hostname. Specify an IP address or a hostname and domain (but do not specify http:// or another protocol). that is.Environment Type: The environment of the IBM Case Manager server. From the drop-down list in the Type field. follow these steps. . If you are accessing a server using SSL security. target object store. Procedure 1. . enter the following information. .Development: The environment where you develop your services. About this task To add a server.Port: The port number of the IBM Case Manager server.labwide. port. A target object store is used to store runtime case solutions. . . Enter a description of what the server does or provides in the Description field. Beneath the Servers heading click Add.Hostname: The hostname of the IBM Case Manager server. the values from the default environment type will be used. see Accessing an IBM Case Manager server using the Secure Sockets Layer (SSL). 2.Production: The environment where your services are deployed for use by your organization.Target Object Store: The target object store name for the IBM Case Manager server. Select the Servers tab from the Process App Settings editor. If you do not provide values for these environments. If you do not know the name. 323 . you should be able to get it from the IBM Case Manager server administrator. You will see the Process App Settings editor when you first click Open in Designer from a newly created process application in the Process Center. use the Hypertext Transfer Protocol Secure (HTTPS) protocol.Test: The environment where you test your services. . 3.com . enter a meaningful name for server. .Default: A set of default values that are used if you do not provide values for the following environment types. select IBM Case Manager Server. connection userid and password) for each environment type. For example:myHost. . Beneath the Server Locations heading. Beneath the Server Details heading.ibm. . if it will be a secure service.Adding an IBM Case Manager server You require at least one IBM® Case Manager server to build an IBM Case Manager Integration service. Alternately you can select Process App Settings from the drop-down list on the toolbar in Process Designer.Secure: Select if you want your service to be secure. .Password: The password of the userid connecting to the IBM Case Manager server.Connection Userid: The userid for connecting to the IBM Case Manager server. Parent topic:Integrating BPDs with IBM Case Manager cases 324 . . Save your work. select File > Save All. From the menu. 4. 3. this service integrates with another system.Retrieve case: This operation retrieves a case. 4. Before developing your service. The drop-down list of servers is located in the Server field. Under IBM Case Manager Server. Open the Process Designer desktop editor. 6. and vice-versa. drag an IBM Case Manager Integration step onto the canvas. Enter a name for the service on the following dialog box and click Finish. Note: The name for the IBM Case Manager solution you will use and the process application that you are currently using to develop your IBM Case Manager Integration service must be identical. follow these steps: Procedure 1. Should there be no entries in the list that means that no servers have been specified. From the palette. See Building a query for a search case operation. you must be in the IBM Process Designer desktop editor. The initial IBM Case Manager Integration step is named Untitled which you can rename to something more appropriate. Should you rename the IBM Case Manager solution in future you will also need to rename the corresponding process application. The case references are returned in an array object. based on a case reference. 2. . Specifically. The library section is found in the upper left area of Process Designer. check that your IBM Case Manager solution name and your process application name match.Create case: This operation lets you create a new case. Click Implementation in the Properties view. that is. 5.Search case: This operation retrieves a set of case references according to a query. Open a process application in the Designer view. . The IBM Case Manager Integration Service editor opens with the Diagram tab in focus. a case instance. About this task To build an IBM Case Manager Integration service. this service integrates a business process developed in IBM® Process Designer with an IBM Case Manager case management solution. select the appropriate operation.Building the IBM Case Manager Integration service Like other integration services. Click Use Process Application Settings to add a server and add a server. Click the plus sign next to Implementation and select IBM Case Manager Integration Service from the menu to create a service that the business process could use later. Under Case Operation. These servers are initially defined under Process App Settings (see Adding an IBM Case Manager server ). A case is an instance of a case type. select a case management server from the list of known servers. It can be used with a search case operation which 325 . Before you begin To perform this task. . Click Generate Types. 8.Note that generating the business objects does not mean that you have created variables with these business objects as types. This section lets you create the map between the variables for input and output. To see the business objects. Save your work to update the process application with any changes to your service. these variables need to be created. 9. See Processing a search case operation result if you want to search for cases and then perform multiple updates by iterating through the array object that is returned. changing a case type name in an IBM Case Manager solution is independent of creating this service. Parent topic:Integrating BPDs with IBM Case Manager cases 326 . Click Data Mapping. 7. For example. Beneath Case Type. select the type of case to use. Click the auto-map icon to create these private variables. 10.provides the case references. which are used by the IBM Case Manager Integration service. The auto-map function creates private variables for the business objects.Update case: This operation lets you modify a case. In other words. . you can create these variables quickly by using an auto-map function. Should your case type change in the future you will need to repeat the previous steps for the new case type name and regenerate the business objects which you do in the next step. As stated previously. click Data. A simple way to both create and map the input and output variables for an operation is to use the auto-map function. a case type for a case pertaining to insurance claims might have an Auto Claim case type. This generation creates the business objects which are used by variables to contain the data transferred between your service and the case management server. You still need to create those variables to handle the input and output data for each operation. In the next step on data mapping. The mapping structure for each operation is discussed in Data mapping in case operations. All returns cases matching all the criteria specified in the case filter. click the Case Filters tab.Date added between: Lets you specify a period of time when a case was added to the case management solution. Save your work. Select the Data Mapping tab in the Properties view to see the Input Mapping field. In the IBM Case Manager editor. . In the left column. if you created more than one search service. the case type in your query will be used.The case type in your query takes precedence over the case type specified in your service. select the search node you want to create your query for. Parent topic:Integrating BPDs with IBM Case Manager cases 327 .Case ID: Lets you specify a case.Modified by: Lets you specify a userid that modified a case. You can improve your response time by qualifying your SELECT clause as follows: SELECT CmAcmCaseIdentifier. About this task Follow these steps to add a query that can be used in a search case operation. Procedure 1.User-specified properties: Lets you specify custom properties found in the case type selected for the node. 2. 4. Beneath Build Case Filter complete the fields appropriate to your query. 3.. complete or failed.Building a query for a search case operation A graphical interface helps you build a query to your IBM® Case Manager solution. . . File > Save All. ..Use Mapping Variable (String): Select this check box only if you are experienced in writing Content Management Interoperability Services (CMIS) queries and want to write your own hand-coded query (see the query section of the CMIS specification for information on the syntax). . Selection will disable the fields in case filter and make the Input Mapping field editable. . .Date modified between: Lets you specify a period of time when a case was modified. . cmis:objectId FROM .Case State: Lets you specify the state of a case: working. .Match criteria: Lets you select all or any as a match criteria.Added by: Lets you specify a userid that added a case. If there is a difference between the case type in your query and the case type in your service. Any returns cases matching any single field in the case filter. local. you could search for a case and for each case reference returned perform a retrieve to get the properties of each case instance. get the next case reference */ if(tw. reset the counter.references[tw.currentReference = null.Processing a search case operation result A search case operation result is often used with an update case operation. It will let the loop run until there are no more cases in the array to process.counter <= tw. For example. The Reference is already null so the decision node should continue */ tw. In the Loop Case References component.local.counter ++. /* Reset the current reference */ /* If the counter is within the length of the array. Procedure 1.references. } 328 .local.counter = -1. /* Assumes that the counter variable will always be reset to -1 at the end of the loop */ tw. /* Increase the counter by one */ tw. 2. create a flow of operations similar to the following screen capture.local. About this task Follow these steps to make multiple updates using a search case result.local.local. In the IBM® Case Manager Integration Service editor. you would use JavaScript to iterate through each element of the array and perform multiple updates. Although this topic is about a search case. }else{ /* Else.listLength){ tw.local. it could also be applied to a retrieve case. You could look upon this example as a pattern that can be used any time multiple case references need to be processed.counter].currentReference = tw.local. add JavaScript similar to the following in the Implementation section of the Properties view. Since an array is returned in a search case result. enclosingCaseInstance system variable as the reference to the case instance running on the IBM Case Manager server. Parent topic:Integrating BPDs with IBM Case Manager cases 329 . 5. return the flow to the Update Case service when the currentReference variable from the JavaScript shown previously is not equal to a null value.system. In the Implementation section of the Properties view for the Decision Gateway . use the tw. 4. Run the business process that invokes this service. This variable is only available at the business process definition level. When you return that case instance to the IBM Case Manager server.A different situation to the one described in the previous steps is if you update a case instance in IBM Process Center that originated on the IBM Case Manager server.3. Create a query to run against your IBM Case Manager solution as shown in Building a query for a search case operation. and assigns variables of the right type to each field. if required. float. It maps to the CaseReference business object found in the System Data toolkit.Return code: A return code indicating if the operation was successful. .Return code: A return code indicating if the operation was successful.Response message: A response message from the server. . string or datetime type. Input and output map for a search case operation Input map: .Response message: A response message from the server. The properties have an integer. Output map: . Output map: .Case properties: An array of key-value pairs to initialize the properties of the case. It maps to the CaseReference business object found in the System Data toolkit. Input and output map for a retrieve case operation Input map: Case reference: A reference to an IBM Case Manager case.CMIS query: A string of text containing the Content Management Interoperability Services (CMIS) query. The types are generated by the Generate Types button when you build your service. Using the auto-map function creates variables. The types are generated by the Generate Types button when you build your service.Input and output map for a create case operation . 330 . .Case instance: An instance of the case type. The cardinality (number of elements) of the properties is either a single element or multiple elements.Input and output map for a retrieve case operation . boolean.Case reference: A reference to the IBM® Case Manager case. . This section shows you the mapping between the input and output fields. or values in the case of input.Input and output map for a search case operation . .Case references: An array of IBM Case Manager CaseReference objects that match the query. Output map: .Data mapping in case operations Each case operation requires that variables. be mapped to the input and output fields. They map to the CaseReference business object found in the System Data toolkit.Input and output map for an update case operation Input and output map for a create case operation Input map: . string or datetime type.Response message: A response message from the server.Case properties: An array of key-value pairs to initialize the properties of the case.Return code: A return code indicating if the operation was successful. float.. Output map: . Parent topic:Integrating BPDs with IBM Case Manager cases 331 .Response message: A response message from the server. . .Return code: A return code indicating if the operation was successful. The cardinality (number of elements) of the properties is either a single element or multiple elements. Input and output map for an update case operation Input map: . boolean. .Case reference: A reference to an IBM Case Manager case. The properties have an integer. It maps to the CaseReference business object found in the System Data toolkit. The types are generated by the Generate Types button when you build your service. use the host name and port that you used in the IBM Solutions Console. Click Ok if the retrieval is successful. Click Retrieve signer information. For stand-alone servers. When you add this secure server in your process app settings page. Click Retrieve from port. 4. Launch the Administrative console and log in to the IBM Integration Solutions Console of the server running your IBM Process Center. Parent topic:Integrating BPDs with IBM Case Manager cases 332 . 3. Click the Secure check box. 5. make certain all nodes are synchronized. in the Port field enter the secure port number and in the Alias field enter an alias name for the IBM Case Manager server you want to connect to. 2. the truststore is called CellDefaultTrustStore. navigate to Security > SSL certificate and key management > Key stores and certificates > NodeDefaultTrustStore > Signer certificates. 7. 6. enter the hostname. In the Host field. About this task These steps show you how to set up a connection to an IBM Case Manager server using SSL.Accessing an IBM Case Manager server using the Secure Sockets Layer (SSL) Some IBM® Case Manager servers may use SSL for security protection. Verify that the retrieved information is the expected signer certificate of your Case Manager server. Procedure 1. Save your work and log out of the IBM Solutions Console. In a Network Deployment (ND) environment. In a Network Deployment (ND) environment. Designing process interactions for business users After you deploy a business process definition that you have built in Process Designer to the Process Portal. This name is visible to business users in the Process Portal. you need to configure different elements in the business process definition (BPD) to control the types of actions that different business users can perform in the Process Portal. In Process Designer. process owners can use the Process Performance dashboard to review the progress of processes and their instances. you can optimize your process to make it more flexible and efficient for the business users who will be working with the application in the Process Portal. If the business process is enabled and process owners are authorized. a business user might interact with it in a number of ways. .Enabling process instance management for a BPD In IBM® Process Portal. The user might have more of a management role. It is important to keep each of these roles. and the dashboards that they can access. allowing them to distinguish between different instances of a process as they complete their work.Configuring a role-based business user interface Before you deploy your process application. they can also act on individual process instances in the Gantt chart to resolve issues. you can change the way the process instance names are generated for a BPD in the Process Portal. . The user might be the one to launch the process. for example.Developing flexible and efficient process applications After you have mapped out your process to include all of the normal task flows for normal process execution. or the user might be assigned individual activities in the process. and their business goals. in mind when you are designing the different features of your process. such as bottlenecks. . or the user might be called upon as an expert to collaborate with another user on an activity.Generating names for process instances When you run a BPD. Parent topic:Creating processes in IBM Process Designer 333 .Setting up collaboration features for business users Business Process Manager provides several features that allow business users to collaborate with other users while working with processes. . IBM BPM creates a default name for the process instance. . monitoring the progress of the process execution. the types of data they can search for and view. Exposing business process definitions Exposure settings for business process definitions (BPDs) enable you to establish who can start the process and perform other tasks in the IBM® Process Portal. and the dashboards that they can access. you need to configure each variable in the Process Designer to be available to search. . . Or they can be exposed as URLs.Making business data available in searches and views Before business users in IBM Process Portal can search for business data across process instances. other people can use the client-side human services that you create in IBM Process Designer to create custom dashboards for IBM Process Portal or instance user interfaces for case instances. the heritage human services that you create in IBM Process Designer can also be used to customize the Process Admin Console or to create a custom dashboard for IBM Process Portal. The exposure settings for a service depend on its intended purpose. the types of data they can search for and view. Parent topic:Designing process interactions for business users 334 .Exposing client-side human services In addition to implementing activities in a business process definition (BPD) or a case type. the business data about a task that business users see in their task list needs to made available to search in order to be viewable in the task list.Configuring a role-based business user interface Before you deploy your process application. you need to configure different elements in the business process definition (BPD) to control the types of actions that different business users can perform in the Process Portal. . .Exposing heritage human services In addition to implementing the activities in a business process definition (BPD). In addition. Start instances of the process in Process Portal . In the Exposing section. 335 . 2. Click the Select button to choose the team whose members can perform ad hoc analysis on this process in the Ad Hoc Reports dashboard in IBM Process Portal. Before you begin To perform this task. Members of the selected team can start instances of the process from the Launch tab in IBM Process Portal.Exposing business process definitions Exposure settings for business process definitions (BPDs) enable you to establish who can start the process and perform other tasks in the IBM® Process Portal. 3. The Ad Hoc Reports dashboard is not exposed by default for Process Portal users. Click the Overview tab. See Exposing the Ad Hoc Reports dashboard.View data for instances of the process in reports in Process Portal Procedure 1. configure the exposure settings to expose different aspects of the process to specific teams. click the X icon next to the exposure setting. Click the Select button to choose the team whose members can view data for this process in the Process Performance dashboard in IBM Process Portal. Settings that can be enabled in the Exposing section Exposure setting Expose to start Expose business data Expose performance metrics Action Click the Select button to choose the team whose members can start instances of this process in IBM Process Portal. If you want process participants to see the Ad Hoc Reports dashboard in their tabs list. Open the Process Designer desktop editor. To remove an assigned team. About this task You need to expose a BPD to particular teams to establish who can: . you must be in the IBM Process Designer desktop editor.Table 1. Open the BPD in the Designer view. 4. you must expose it manually. you must expose the Ad Hoc Reports dashboard manually. Parent topic:Configuring a role-based business user interface Related information: Creating a team Activating snapshots for use with IBM Process Portal 336 . If you want exposed BPDs and data from a particular snapshot to be available in IBM Process Portal while under development on the Process Center Server.5. When you deploy snapshots of process applications on Process Server in other environments.Exposing the Ad Hoc Reports dashboard If you want IBM Process Portal users to see the Ad Hoc Reports dashboard so that they can generate dynamic reports directly from IBM Process Portal. Save your changes. . such as test and production environments. Exposed BPDs and data from the current working version are always available in IBM Process Portal. you need to activate the snapshot (version) that you want. However. Anyone with administrative access to the process application can activate snapshots. those snapshots are active by default. 5. click Select next to the Exposed to field to choose the team whose members can view and use the exposed Ad Hoc Reports dashboard. Before you begin To perform this task. go to User Interface > Heritage Human Service and open the Ad Hoc Reports dashboard that you want to expose. Click the Overview tab. To create a team. To remove an assigned team. click New. Open the process application in the Designer view and click User Interface. Parent topic:Exposing business process definitions 337 . Save your changes. you must be in the IBM Process Designer desktop editor. Procedure 1. 6. In the library. 3. In the Exposing section. 2. click the X icon next to the Exposed to field. Open the Process Designer desktop editor. you must expose the Ad Hoc Reports dashboard manually.Exposing the Ad Hoc Reports dashboard If you want IBM® Process Portal users to see the Ad Hoc Reports dashboard so that they can generate dynamic reports directly from IBM Process Portal. 4. The name of the individual page in the new category matches the service name.Exposing heritage human services In addition to implementing the activities in a business process definition (BPD). the heritage human services that you create in IBM® Process Designer can also be used to customize the Process Admin Console or to create a custom dashboard for IBM Process Portal. 338 . click the X icon next to New. Startable Service (Launch from Process Use this option to enable members of Portal) the selected team to start the service from the Launch sidebar in Process Portal. Before you begin To perform this task. 3. To remove an assigned team. Administration Service (Available in the Use this option to make the heritage Process Admin Console) human service available to members of the selected team as a separate page in the Process Admin Console in the Server Admin capabilities. specify the exposure type by selecting one of the following options. In the Exposing section. Exposing options Option Description Do Not Expose (Service contained in a Use this default option for services that BPD) implement the activities within a BPD. Open the heritage human service that you want to expose and click the Overview tab. 4. click New. the Exposed to setting is not used. To create a team.Table 1. A new category is added to the menu. In the Expose As list. you must be in the IBM Process Designer desktop editor. click Select next to Exposed to to choose the team whose members can view and use the exposed service. For information about exposing client-side human services. The exposure settings for a service depend on its intended purpose. Open the Process Designer desktop editor. which has the same name as the process application that contains the service. 2. see Exposing clientside human services. When this option is selected. Procedure 1. you must complete the following steps:Create a snapshot of the toolkit. and the acronym for the process application that contains the service. URL (Available from a URL only) Use this option to make the service available from a URL address. See Activating snapshots for use with IBM Process PortalAdd the toolkit snapshot as a dependency to a process application. changing. If you want to expose the dashboard outside of Process Portal. For more information about how to configure a custom context root. if you expose a service named MyService. and selecting the dashboard from the list of hidden pages. For information about the REST API that provides the URL for the exposed service. Team members can access the dashboard by clicking the Organize tabs icon . For example. The URL is composed of the name of the host on which IBM Process Center Server or Process Server is installed. click Select next to the Label field and select the key in the resource. all exposed heritage human services are made available to be called as URLs. See Globalizing dashboard names.Activate the toolkit snapshot. generate a portlet that you can deploy to a portal server by clicking Create a Portlet from the Dashboard. and deleting a toolkit dependency in the Designer view.Remember: Any browser339 . Results In addition to being exposed to user interfaces as described in the previous table. you can access it from the following URL: http://host_name:port/contextRootPrefix /executeServiceByName?processApp=acronym&serviceName=MyService The default value for the contextRootPrefix is teamworks. see the section for the -update parameter in the BPMConfig command-line utility topic.Exposed Items Resource. see REST Interface for BPDrelated Resources . the port that is designated for the server during the IBM Business Process Manager installation. If you defined a localization resource for your dashboard name. See Creating. If you do not specify a localization resource for the dashboard name.Dashboard (Available in Process Portal Use this option to make the heritage Dashboards menu) human service available in Process Portal to members of the selected team. the dashboard page has the same name as the exposed service. If the heritage human service is in a toolkit. variableName can be a system-defined SimpleType or a BusinessObject that is based off a SimpleType variable (of type String. Integer. such as the URL length and character restrictions.The name of the heritage human service .The URL of the error page . see The 99Local. For more information.xml file.xml file to enable the type-string-to-date configuration option:<common merge="mergeChildren"> <type-string-to-date merge="replace">true</type-string-to-date> </common> . .serviceName .The name of the snapshot .The URL can contain one or more of the following parameters: . the following example shows how to customize the 100Custom. Integer.variableName=value The default configuration is defined in the 99Local. For more information. Date. Date or Time are allowed only after enabling the type-string-to-date configuration option. Decimal. .In the URL.Input variables . . the default time zone is set to the time zone of the 340 .The Date format is YYYY-MM-DD.xml file to enable the type-string-to-date configuration option:<common merge="mergeChildren"> <type-string-to-date merge="replace">true</type-string-to-date> </common> For heritage human services. The syntax for the other simple types (String. input variables that are defined for the service have the following format:&tw. Time.xml file.Time Zone: Because support for time zone information is not provided with heritage human services.processApp . see The 99Local.snapshot . apply and must be considered when calling a heritage human service as a URL.The Time format is HH:mm:ss. Decimal.Note: For information about the date and time syntax in human services.errorPage . see Exposing client-side human services.For heritage human services. the following example shows how to customize the 100Custom.xml and 100Custom.com.The date and time format differs between client-side human services and heritage human services.The name of the process application .URL parameters . . Restriction: The type-string-to-date configuration option is applicable only to heritage human services. Selection) is the same for client-side human services and heritage human services.lombardisoftware. Also. The default configuration is defined in the 99Local.xml and 100Custom. the date and time format is as follows: . . Selection).Date/Time syntax .specific URL limitations. Also.xml configuration files.xml configuration files.local. It does not apply to client-side human services. You can export only one valid snapshot when you generate a portlet for a dashboard. you must configure the com.Enabling resumable services To enable resumable dashboards for a process application.If a specific snapshot name is not passed to the URL. Table 2. the default version of the service that is run depends on the environment in which the service is running. Version of the heritage human service invoked for each environment Environment Process Center Version of the heritage human service The exposed service in the tip of the default track is run. Then the portal server administrator can deploy the JSR 286 portlet to the portal server runtime environment. . then the latest snapshot version is started. Process Server Process Portal A portlet in an external portal server . the version that is started is the current working version of the heritage human service if the version is exposed. then the snapshot version is started.Globalizing dashboard names If you want dashboard names in Process Portal to be available in multiple languages. if there is an active snapshot in which the heritage human service is exposed. Parent topic:Configuring a role-based business user interface Related information: 341 .Service version invoked . The exposed service in the default snapshot is run.ibm. When you start a heritage human service as a dashboard in Process Portal.Generating portlets for heritage human services exposed as dashboards If you exposed a heritage human service as a dashboard for a group of process participants. If the current working version is not exposed and there are multiple active snapshots in which the heritage human service is exposed.social. When the portlet communicates back to IBM Business Process Manager.bpm. generate a portlet. define a localization resource for each dashboard name.server. . and you want to use the dashboard in IBM WebSphere® Portal.zResumable property. Otherwise. . that snapshot must be active. Exposing client-side human services Creating a team Activating snapshots for use with IBM Process Portal Generating portlets for heritage human services exposed as dashboards 342 . When a service is resumable.ibm. or the session times out due to inactivity. The service state and any service variables set from the prior instance invocation are still in session memory and are used. Dashboard Services called from Process Portal can be configured to be resumable (called with zResumable=true). Startable services that are called from the Process PortalLaunch list and administrative services that are called from the Process Admin Console are not resumable. If the Process Portal user navigates away from a heritage human service Coach. A new service instance is created each time the service is invoked.zResumable property.social. and the next time the service is resumed. which can potentially utilize a large amount of server memory per user. a service instance is reused if a previously created service instance is still available in the Process Portal user’s session. Note: Only services invoked in a snapshot can be resumed. Therefore.Enabling resumable services To enable resumable dashboards for a process application. Procedure 343 . the service instance remains in the user's session. . . Therefore. you must configure the com.Resumable services . services should typically flow to an end node so that the service is removed from the Process Portal user's session immediately.By default. About this task When an exposed heritage human service is invoked. which supports iterative development scenarios on Process Center. the service is never resumed.Services can be called as resumable (called with zResumable=true). which allows Process Portal users to continue where they were when they logged out. If the service does not flow to an end node.bpm. If the dashboard service flows to an end node. consider the various service types and the service lifecycle when authoring and exposing a heritage human service. If the service does not flow to an end node.Non-resumable services . the service instance is removed from the session. each instance remains in the Process Portal user's session (until logout or session timeout). the service instance and associated data remains in the Process Portal user's session memory until one of the following conditions occurs: the heritage human service ends. which might result in large memory allocations if many service instances accumulate. one instance remains in the session and is available for reuse (until logout or session timeout). When invoking a service in a tip. services are not resumable. Resumable services are often authored so that they do not end. the Process Portal user is prompted to restart the service. the Process Portal user logs out. Sessions are held in IBM® Business Process Manager server memory. The resumable instances are stored per user session. you can use a clientside key as a reference to resume and reference multiple dashboard instances. If the process application for the dashboard is added to the com. The default value for the contextRootPrefix is teamworks.zResumable list. for example. see Session management settings in the IBM WebSphere® Application Server documentation. With these parameters. Save your changes 4.This parameter causes the user's dashboard session to be resumed.ibm.bpm.To enable resumable dashboards for a process application. It is appended by default to all dashboard URLs. The dashboards delivered in the Process Portal application are not designed to be resumable.[zClientHandle={key}] .social.ibm.ibm. all resumable instances are cleared. 2. Create a property named com.social. you can use the following resumable parameters: . dashboard services called from Process Portal are automatically called with zResumable=true.MAILCOM. Open the administrative console and click Resources > Resource Environment > Resource Environment Provider > Mashups_ConfigService > Custom properties. 5.social.bpm. 6. see the section for the -update parameter in the BPMConfig command-line utility topic.If you use the URL to launch the dashboard as part of an application that runs outside of Process Portal. you must configure the com. for example: TRD.zResumable property: 1. The parameter can be used with the optional zClientHandle={key} parameter. Restart the server. . you can use this optional parameter with the zResumable=true parameter.zResumable and set its value to be a list of process application IDs.If you use the URL to launch the dashboard as part of an application that runs outside of Process Portal.social. so different users have different instances. For information about HTTP session settings including session timeout intervals. For more information about how to configure a custom context root. Parent topic:Exposing heritage human services 344 .zForceNew=true . by modeling an end event in the service. Invoke resumable services by using the following URL: http://host_name:port/ contextRootPrefix/executeServiceByName?processApp=acronym &serviceName=MyService. If you use this parameter. Important: Do not add the Process Portal (TWP) process application to the com.bpm.zResumable=true .bpm. . When a user logs out. you must ensure that services are terminated.ibm. or by calling an API to complete or terminate the service. you can use this parameter to override the zResumable=true parameter so that a new dashboard instance results. 3. In addition to the standard service URL parameters.zResumable list.RD. 345 . Globalizing dashboard names If you want dashboard names in Process Portal to be available in multiple languages. In the window that opens. C. Procedure 1. B. click Select next to the Label field. Select a localization key from the resource bundle group that you want to apply to the dashboard label. 2. A. hover over Setup and click the Add icon. The New Localization Resource wizard opens. 3. D. Select the resource bundle group that you created in the previous step. define a localization resource for each dashboard name. link the resource bundle group to your dashboard. Parent topic:Exposing heritage human services Related information: Customizing the IBM Business Process Manager dashboards 346 . In the library for your process application. select Localization Resource. Click Link Localization. On the human service Overview tab. A. Save your changes. Enter a name for the resource bundle. Define a new resource bundle group in Process Designer. On the dashboard Variables tab. Add localizations and localization keys to the resource bundle group. B. When you design heritage human services that you intend to expose as dashboards that are deployed as portlets. consider the following guidelines: . If you complete the following procedure. .Typically. pay attention to where the processing occurs in relation to the boundary event. .Make sure that the IBM WebSphere Portal server is added to the trusted server list as described in Adding servers to the trusted server list. . make sure that the payload variable is included on each coach 347 . and that the heritage human service is exposed as a dashboard. Make sure that the heritage human service has at least one snapshot and one coach. heritage human services that are exposed as dashboards are not services that end.If you are planning to designate a payload variable for inbound or outbound events for the dashboard. . . add a new boundary event that loops back to the same coach that is specified as part of an inbound event. However. Remember that when a dashboard portlet is deployed. make sure that all boundary events on the coaches have unique control IDs. the dashboard also is available for the specified users as a portlet deployed on a WebSphere Portal server. you are not prohibited from using end events in the heritage human services that you expose as dashboards.If you are planning to update variables within a coach from an inbound event. and it contains an endpoint. but you do not want trigger any of the boundary events for the coach.If you use preprocessing and postprocessing for the heritage human service. you might need to move preprocessing and postprocessing so that the boundary event triggers properly in the dashboard portlet. Then the portal server administrator can deploy the JSR 286 portlet to the portal server runtime environment.Generating portlets for heritage human services exposed as dashboards If you exposed a heritage human service as a dashboard for a group of process participants. the portlet ends. If your coach is designed to end the service.Work with the portal server administrator to understand how the dashboard portlets are related to other portlets and services in the portal server runtime environment. Make sure to select the new boundary event when you define the inbound event for the generated dashboard portlet. and it must be restarted. If the boundary event control IDs are not unique. Before you begin Make sure that the heritage human service is exposed to the appropriate group of process participants who work with the dashboard at run time. Because portlets can be wired together and wired to other services. . The dashboard is available for the specified users in Process Portal by default. and you want to use the dashboard in IBM® WebSphere® Portal.If a heritage human service contains two coaches with the same name.You can generate portlets for dashboards that contain heritage coaches. but you cannot map heritage coaches to boundary events for dashboard portlets. generate a portlet. the generated dashboard portlet includes a Reload button for process participants to start a new instance and refresh the dashboard. . process participants who use the dashboard portlet might receive errors or unexpected portlet interactions. The XML must be ready before you start the Export Dashboard wizard. which is available at http://www. click Create a Portlet from the Dashboard on the overview 348 . The description and display-name elements cannot have empty string values.txt.0' encoding='UTF-8' ?> <portlet> <description xml:lang="en">English description</description> <description xml:lang="fr">French description</description> <description xml:lang="es">Spanish description</description> <display-name xml:lang="en">English display name</display-name> <display-name xml:lang="fr">French display name</display-name> <display-name xml:lang="es">Spanish display name</display-name> </portlet> Ensure that the XML file has encoding defined as UTF-8. specify the same security protocol that is used by the IBM BPM server. . Ensure that the XML uses the same format as the following example:<?xml version='1. For example.that is part of the heritage human service.The collaboration feature is not available for dashboards exposed as portlets. The XML file can contain zero or more description or display-name elements. make sure to prepare an XML file that you designate when you create the portlet from the dashboard. The payload variable must be included on each coach that is part of the heritage human service that is exposed as a dashboard and deployed as a portlet. users cannot interact in an activity with other users or experts like they can in Process Portal. . your portal server administrator can deploy the portlet to IBM WebSphere Portal so that the process participants interact with the dashboard in the runtime environment. use HTTPS for both the IBM BPM server and the portlet running on the IBM WebSphere Portal server. After you generate a portlet for the dashboard. For heritage human services that are exposed as dashboards for a group of process participants. Procedure 1. or use HTTP for both the IBM BPM server and the portlet running on the IBM WebSphere Portal server.ietf. The xml:lang attribute must follow the RFC 1766 specification.For globalization support for the name and description of the generated portlets. About this task Use the Export Dashboard wizard in Process Designer to define portlet parameters and map events when exporting the dashboard.org/rfc/rfc1766. That is. When you configure the portlet on the IBM WebSphere Portal server and specify the IBM BPM URL. .Using the same security protocol for both the IBM BPM server and the IBM WebSphere Portal server prevents an issue where Process Portal users see a blank task completion view in an IBM WebSphere Portal portlet. a coach can include a variable without displaying it to process participants if you add a field for the variable to the coach and set the visibility of the field as None (hide or disable). However. make sure to select a coach that has the same variable.0 provider already installed. . it fires a boundary event. moving the dashboard to another coach. The IBM BPM server comes with a WSRP 2. Optional: Define inbound events for the dashboard portlet. ensure that the payload variable is included on each coach that is part of the heritage human service. The boundary event in a heritage human service diagram is labeled as End State Binding. consider how the portal server administrator and the process participants use the deployed portlet: . ensure that the payload variable is included on each coach that is part of the heritage human service. For information on using WebSphere 349 . The namespace default value makes the event unique and prevents unintended interactions between portlets. .war file on your IBM BPM server and tell the portal server administrator to point to the endpoint for the Web Services for Remote Portlets (WSRP) 2. 5. When the dashboard portlet receives an event from another portlet. When setting the parameters for the portlet. . As previously mentioned. which allows consumption of portlets generated from WebSphere Portal.When the dashboard portlet receives the event. . changes after the snapshot was taken are not represented in the generated portlet.At run time. The URL for accessing the WSPR 2.If you created an XML file for globalization of the name and description of the portlet.Select a boundary event to designate user interface elements that cause the dashboard portlet to send the event.war file. change the event name field to something meaningful to your dashboard.If you specify a payload variable.Select the snapshot that represents the version of the dashboard that you want to be generated as a portlet for process participants to use at run time. You can choose from variables that are part of the heritage human service.Define multiple interface elements by clicking the plus sign and designating another coach and boundary event. If the coach uses a payload variable. the dashboard portlet includes data in the sent event for other portlets to use.Specify a payload variable if you expect the inbound event to contain data that you want to use to update the dashboard data.At run time. other portlets interact with the dashboard portlet by sending events to it. install the .Enter a name and a description that describe what the portlet does. it interacts with only the interface element on the currently displayed coach. . As previously mentioned.Select a coach and a boundary event that represents the user interface element that you want the dashboard portlet to interact with when it receives the event. Optional: Define outbound events for the dashboard portlet. . select the payload variable that the dashboard portlet receives from other portlets at run time. After you finish exporting the dashboard as a portlet. the dashboard portlet sends events to other portlets. .page in Process Designer to open the Export Dashboard wizard.0 provider web service on an installed IBM BPM server is: http://{BPM_host_name}:{BPM_port }/producer/wsdl/wsrp_service. 4. 3. If you select an older snapshot. 2.wsdl. select Globalization and browse to the file.For each inbound event that you want this dashboard portlet to respond to. . . If you selected a payload variable.0 protocol and import the . Give the administrator information about the following IBM BPM portlet preferences that can be edited in the dashboard portlet. . Tip: The WSRP Producer for WebSphere Application Server is a stateless producer and does not manage any portlet preferences on the server.A boolean value to indicate if Dojo should be used when available for client-side events. If the value is false. The keyword makes it easier for administrators to find and manage the dashboard portlets.war file to the portal server administrator to deploy. If you are not using WSRP. .The administrator should install dashboard portlets on the same cluster as Process Portal. .xml file that is contained in the exported .bpmHost (default: localhost) . the portlet tests if Dojo is loaded and uses the Dojo publish-subscribe methods to send and receive events.The port number for the server . and height. If the value is true. Discuss the following points with the portal server administrator: . port number. administrators should enable and configure single-sign-on for the WebSphere Portal and IBM BPM servers.The height (in pixels) to be used for the portlet iframe that displays the dashboard . width.war file with any portlet preference changes before the administrator installs the .bpmHeight (default: 400) . All other IBM BPM portlet preferences should not be changed. see Using WSRP services on the IBM WebSphere Portal wiki. you must update the portlet.bpmWidth .To avoid browser messages about secure connects for process participants who connect to WebSphere Portal and use the dashboard portlets. administrators should replace personal.war file.The width (in pixels) to be used for the portlet iframe that displays the dashboard . the portlet uses server side-events as specified in JSR286. . . If you are using the WSRP Producer.bpmUseSSL (default: false) . self-signed certificates with those provided by a trusted external certificate authority (CA).Make sure that the administrator knows that portlet preferences can be edited in WebSphere Portal using the edit page for the portlet.Tell the administrator the following requirements for using single-sign-on (SSO) and Secure Sockets Layer (SSL) protocol in WebSphere Portal with the dashboard portlets from IBM BPM.The host name or IP address for the server .The indication that https should be used instead of http .bpmPort (default: 9080) . .To prevent the Process Portal login panel from appearing in the dashboard portlet. .Notify the administrator that the IBMBPM keyword is added to the generated dashboard portlet. See Single sign-on for authentication in the WebSphere Application Server information center.bpmUseDojo (default: true) . give the . 350 . See Creating a certificate authority request in the WebSphere Application Server information center.Portal with a WSRP provider. The administrator can edit the following information for the dashboard portlet that is generated: host name. .. and other parts are loaded using HTTP. which requires two steps: Installing a new theme and enabling the full profile to use Dojo by default as described in Theme enablement.In a production environment. Server-side events do not require the Dojo Toolkit to be loaded and are the standard event mechanism defined in the JSR286 specification.If the administrator decides to use client-side events.If using HTTPS to connect to WebSphere Portal.0. The generated dashboard portlets receive server-side events from other portlets on the page that are not using client-side events. administrators should avoid using self-signed certificates. the Dojo Toolkit must be loaded as part of the theme for the portal page. See the WebSphere Portal V8 documentation Changing the theme default profile or the WebSphere Portal V7. the portlets created with Process Designer use the Dojo Toolkit to send messages between portlets that are on the same page in the portal server. If client-side events are used.When using client-side events. and the generated dashboard portlets send events using only the Dojo Toolkit.0. Using client-side events is faster. Server-side events can be used across portal server pages with the correct portal configuration and wiring. . . Parent topic:Exposing heritage human services Related information: Exposing heritage human services 351 . because it does not require events to be sent to the server for processing and does not require page reloads when an event is sent or received. Both client-side events and server-side events use the boundary events that are modeled as part of the heritage human service definition. the administrator can import the certificates from each system into the browser before testing.If using personal certificates for testing or in a pre-production environment. . The difference between client-side events and server-side events is the channel for communication. If a part of a page is loaded using HTTPS.2 documentation. process participants who connect to WebSphere Portal and use the dashboard portlets might receive a warning that some content on the page is not secure. the administrator should also use HTTPS in the dashboard portlets.The portal server administrator should determine whether to use client-side events or server-side events. Server-side events take longer to process because the events must be sent to the server for processing and the page must be reloaded to display the results. the Dojo Toolkit must be loaded as part of the theme for the portal page. When this option is selected. 352 . Exposing options Option Description Do Not Expose (Service contained in Use this default option for client-side a BPD or case type) human services that implement activities within a BPD or a case type. other people can use the client-side human services that you create in IBM® Process Designer to create custom dashboards for IBM Process Portal or instance user interfaces for case instances. you must be in the IBM Process Designer desktop editor.Table 1. Open the Process Designer desktop editor. Open the client-side human service that you want to expose and then click the Overview tab. Note: For information about exposing heritage human services.Exposing client-side human services In addition to implementing activities in a business process definition (BPD) or a case type. About this task The exposure settings for a service depend on its intended purpose. specify the exposure type by selecting one of the following options. 3. Or they can be exposed as URLs. Startable Service (Launched from Use this option to enable members of Process Portal) the selected team to start the client-side human service from the Launch sidebar in Process Portal. Procedure To expose a client-side human service. In the Exposing section. 2. complete the following steps: 1. in the Expose as list. Before you begin To perform this task. the Expose to start setting is disabled. see Exposing heritage human services. the URL is displayed as a link that you can either click or copy and paste into your web browser. See Globalizing dashboard names. If the client-side human service is in a toolkit. To copy the URL. For information about the REST API that provides the URL for the exposed service. See Creating. changing.Exposed Items Resource. the dashboard page has the same name as the exposed service. click Select next to the Label field and select the key in the resource. Copy Link Location in Mozilla Firefox or Copy link address in Google Chrome). and deleting a toolkit dependency in the Designer view. URL (Available from a URL) Use this option to make the service available from a URL address. see REST Interface for BPDrelated Resources . you must complete the following steps:Create a snapshot of the toolkit. Team members can access the dashboard by clicking the Organize tabs icon and selecting the dashboard from the list of hidden pages.For fast access. If you do not specify a localization resource for the dashboard name. 353 .Dashboard (Available in the Process Use this option to make the client-side Portal Dashboards menu) human service available in Process Portal to members of the selected team. right-click the link and select the option provided by your browser to copy the URL (for example.If you defined a localization resource for your dashboard name. See Activating snapshots for use with IBM Process PortalAdd the toolkit snapshot as a dependency to a process application.Activate the toolkit snapshot. .[ss] specifies a zero-padded second between 00 and 60 (where 60 indicates an added leap second). the URL can include the following additional parameters.The Date format is YYYY-MM-DD. the Expose as and Expose to start settings in the Overview folder are disabled. . 354 . the time might be displayed as 13:47:30. is assumed to be the local time. Decimal.Date/Time syntax . Integer. as defined by RFC3339. The exposure of this client-side human service is determined only by the settings in the Views folder of the corresponding BPD or case type.Note the following time zone designators for Time: . see Exposing heritage human services. For example. 14:45:15 UTC can be 14:45:15Z. . apply when a client-side human service is called as a URL.Remember: Any browser-specific URL limitations. the date and time format is specified by a profile of the ISO-8601 standard. For example.[mm] specifies a zero-padded minute between 00 and 59. such as the URL length and character restrictions. . Selection) is the same for client-side human services and heritage human services. When you create the BPD or case type and create the details user interface under Details UI in the Views folder.Do Not Expose (Instance details UI for a BPD or case type) Use this option to indicate that the client-side human service cannot be exposed because it implements an instance details user interface that is used for a process instance or case instance. the time. . .If no UTC relation information is given with a time representation. . When this option is displayed for a client-side human service. input variables that are defined for the service have the following format:&tw.Note: For information about the date and time syntax in exposed heritage human services. .local. you also create the client-side human service that implements the user interface for the specified process or case instance. <time>.For client-side human services.variableName=value .[hh] specifies a zero-padded hour between 00 and 24 (where 24 indicates midnight at the end of a calendar day).Input variables . where .The date and time format differs between client-side human services and heritage human services. For client-side human services.The Time format is [hh]:[mm]:[ss]. The <time>Z parameter refers to UTC time.In the URL. The syntax for the other simple types (String. To create a team.. the snapshot version is started. To remove an assigned team. the version that is started is the current working version of the client-side human service if the version is exposed. Parent topic:Configuring a role-based business user interface Parent topic:Modeling client-side human services 355 . Otherwise. Results The default version of the exposed service that runs depends on the environment in which the service is running.Table 2. . if there is an active snapshot in which the client-side human service is exposed. the following times refer to the same moment: 18:30Z. click New. If the current working version is not exposed and there are multiple active snapshots in which the client-side human service is exposed. 22:30+04.The following parameters are time zone offsets from UTC time:<time>±hh:mm <time>±hhmm <time>±hh For example. Click Select next to Expose to start to choose the team whose members can view and use the exposed service. the latest snapshot version is started. When you start a client-side human service as a dashboard in Process Portal. click the X icon next to New.The combined Date and Time format is <date>T<time>. 1130-0700. 4. and 15:00-03:30. for example 200704-05T14:30Z or 2007-04-05T12:30-02:00. The version of the exposed service that runs is the one that is in the default snapshot. Default version of the client-side human service for each environment Environment Process Center server Process server Process Portal Default version of the client-side human service The version of the exposed service that runs is the one that is in the current working version of the default track. the label for the variable in Process Portal will be Customer Name. If you use camel case. Note: The search alias must be unique to the variable type throughout the process server on which the BPD runs. For complex variables. These are the variables that you need to configure in the Process Designer to be searchable and viewable in the IBM Process Portal. type a name for the variable. or which provides a quick way for users to understand something about that task instance without opening the coach for the task. For each variable whose runtime values you want to search or to make viewable in the IBM Process Portal task list. inside human services.Making business data available in searches and views Before business users in IBM® Process Portal can search for business data across process instances. In addition. 2. a parent process and its linked processes) and you want the variable to be searchable in all of those processes. a mix of upper and lower case letters to indicate word boundaries. You also should consider which business data provides necessary information about a task to help users complete the task from the task view if it is an in-line task. In the Alias text box. Save your changes. you must define the same search alias for the variable in each of the BPDs where it is used. If a variable is shared by multiple BPDs (for example. About this task As you model the business data for your process application. Open the Process Designer desktop editor. This is the name to use when performing searches in IBM Process Portal. but not variables defined.Note: Only processlevel variables can be made available as business data for searches. consider what type of data a business user might want to search on while working with the process. if your search alias is customerName. 3. you must be in the IBM Process Designer desktop editor. For example. be sure to select the check box for each parameter you want to make available. 356 . the label for the variable will be parsed into a multi-word string. 4. you need to configure each variable in the Process Designer to be available to search. Before you begin To perform this task. Procedure 1. for example. Open a business process definition (BPD) that includes the variables you want to configure and go to the Variables tab. This is also the name that is seen by users in Process Portal when they are viewing the data related to tasks in their task list. 5. select the Visible in Process Portal check box in the Business Data section. the business data about a task that business users see in their task list needs to made available to search in order to be viewable in the task list. What to do next Your IBM Business Process Manager administrator can create saved searches to provide IBM Process Portal users with customized views of their tasks. Parent topic:Configuring a role-based business user interface Parent topic:Business objects and variables Related information: Declaring variables for a BPD or a service in Process Designer Creating and maintaining saved searches for Process Portal 357 .Results Now when IBM Business Process Manager runs instances of the BPDs that contain the configured variables. The variables that have been made available to search are also viewable to business users viewing the associated task in their task list." users cannot search for tasks using business data declared in the BPD or subprocess even if that data has been specified as "Visible in Process Portal". you can search for process instances that include these variables in IBM Process Portal. Note: If a BPD or subprocess contains a linked process or subprocess that has been specified as "Loop Type: Multi Instance Loop" with "Run In Parallel. or a simple decision. .Configuring activities for inline completion Some activities in your process application can be completed with a single action. you can enable the optimization of execution for latency. such as an approval. you can configure these activities to be performed by the business user in Process Portal with a single click action that does not necessitate the user opening the coach interface. you can configure individual activities to launch automatically if they are assigned to the same person as the previous task. When enabled. if the owner of the first task is the same as the owner of the second. you can design the task so that the business user can complete it in the Process Portal without having to open the coach for the task. rejection. . such as to approve or reject a request or to choose between a set of options.Not all process activities run predictably in each execution of a process. In the Process Portal. other paths are scheduled to use the default shared pool of threads. the second task will launch automatically when the first task is complete. there are several things that you can do to save the business user's time and make it easier for them to complete their work: Procedure .Optimizing BPD execution for latency Select the optimization for latency to reduce thread context-switching for BPDs that require low latency responses.Developing flexible and efficient process applications After you have mapped out your process to include all of the normal task flows for normal process execution. such as updating customer contact information. Ad hoc processes are actions that you can expect users to do at some point during at least some process instances. they might need to cancel the process or they might need to complete a separate but related business action. In Process Designer. This optimization means that one path through the BPD is performed using a single thread on a cluster member. . You can add ad hoc start events and subsequent activities to your BPD. For example. Using the services provided in the system toolkit in Process Designer. the user clicks a button or chooses between the options with a single click.Sometimes multiple sequential tasks in a process are assigned to the same user. and the business user is able to launch the ad hoc process from the Process Portal environment. you can optimize your process to make it more flexible and efficient for the business users who will be working with the application in the Process Portal. .If your process must have a low latency. to achieve a business service level agreement. Instead. . About this task At design time. for example. Sometimes a user must launch a new task that is outside of the normal process flow. this optimization causes the BPD to keep its execution thread rather than releasing it back to the pool of 358 .If your process includes user tasks that involve a simple decision. actions to be launched by the user from action menus in the Process Portal. such as updating a customer's contact information or canceling the process instance. Parent topic:Designing process interactions for business users 359 . .Automatically starting the user's next task To help your business users be maximally efficient while they are using your application. .threads that are shared between activities. consider places in your process where you expect the same user to be completing multiple tasks in sequence.Defining ad hoc actions (deprecated) While a process is running. or ad hoc. The process designer can define a set of these unplanned. a user might need to launch a new activity or set of activities. or a simple choice between a set of options. Inline completion task type characteristics Task Type Simple Approval Usage Inputs Use when the None. task requires the business user to indicate an approval or rejection based on the task narrative and the task details that are exposed in the task list. rejection.Table 1. About this task There are three types of tasks that can be configured to be completed by the user from within their task list without requiring the user to open the coach interface: a simple approval or rejection. 360 Outputs approved Type: Booleancommen t Type: String . such as an approval. Using the services provided in the system toolkit in Process Designer. a simple completion.Configuring activities for inline completion Some activities in your process application can be completed with a single action. you can configure these activities to be performed by the business user in Process Portal with a single click action that does not necessitate the user opening the coach interface. Before you begin To perform this task. you must be in the IBM® Process Designer desktop editor. or a simple decision. A pprove. in a simple completion task the user might only need to indicate that they have reviewed the task narrative and the exposed task details. Instead. select User Task as the task type. tw.R eject Restriction: Do not use JavaScript variable references in task narratives if you need the data to be available after the task completes. comment Type: String choices Type: decision Type: String. 2. Stringcomment By default these Type: String choices are tw. Open the business process definition (BPD) in the Designer view. Select the predefined Human Service that corresponds with the type of inline task that you are creating: Simple Approval.resource. None. Select the task that you would like to configure for inline completion. Procedure 1. List.S impleChoice.S impleChoice. IBM BPM removes the data for completed tasks to conserve space.Simple Completion or Simple Choice 361 . Once a task is complete. In the Implementation tab of the Properties view. Use when the task requires the business user to choose between a list of options. and include a comment. 3. Open the Process Designer desktop editor. For example.Simple Completion Simple Choice Use when the task requires the business user to indicate task completion based on the task narrative and the task details that are exposed in the task list. 4. 5. such as a database. store the data items in another location.resource. These options will each appear as a button in the Process Portal task list. the default appears as follows: var autoObject = new tw. add an autoObject[n] parameter and a string value.String().arrayOf. assign it type String and select the Is List check box. you can modify the choices presented to the user. the inputs and outputs required by the predefined service are already added. Under Default Value. then you must map this variable to the choices(List of String) variable associated with the Simple Choice service. The list of options. select the Has Default check box.. and provide additional choices. which appear as button labels in the Process Portal interface. E. you might have the following: var autoObject = new tw. For example. autoObject[0] = "". When you first create your variable. autoObject For each option that is presented to the user. If you are creating a Simple Choice task. create a private variable to represent the different options that are presented to the user. B. Parent topic:Developing flexible and efficient process applications Related information: Mapping input and output data for an activity or step 362 .object. In the Variables tab of the BPD. if you are creating inline completion buttons for computer configuration. Ensure that you have enabled The IBM BPM Advanced Features by going to File > Preferences > IBM BPM > Capabilities. Note: When the user is completing a Simple Approval task. A. are added as string values for the autoObject[n] parameters. autoObject[1] = "Dual Core". autoObject[2] = "Quad Core". C. The check box for IBM BPM Advanced Features should be selected. 7.arrayOf. D.object. Save the BPD.String(). For example. they must enter a comment if they select the reject option. if you created a simple choice task drawing from a list of options defined in a private variable. . autoObject F. 6. Because the variable will contain a list of strings. autoObject[0] = "Single Core". In the Data Mapping tab. Map the relevant variables that are specific to your process to the data required by the predefined service. otherwise the wait time to acquire one execution thread might increase for your process instances.Do not enable this optimization option for all BPDs in your system. undercover agents. Every cluster member has one Event Manager. 363 . instances return their execution threads to the shared thread pool. which means that the thread is released after each unit of work.BPD system tasks and decision tasks that are optimized for latency are executed on the same thread that the BPD uses for navigation. which means that. only one path is executed by the same thread. However. This optimization setting defines two classes of BPD: . services. If a straight-through processing BPD does not contain any parallel paths. the other paths are scheduled to use the default behavior by the Event Manager. By default. and other functions that use the shared pool of threads. You must take care to avoid causing a negative performance impact on other instances.The default processing behavior is not optimized for latency. If multiple system tasks or decision tasks exist in parallel paths of the BPD. This behavior ensures that all BPD instances that use the default setting have an equal chance to continue navigation of the process. Process instances with this execution optimization use the Event Manager threads for longer and so they provide a more predictable latency. which uses a pool of threads to schedule work in the order that it was created. This thread sharing behavior can increase the latency for the overall process instance. new BPDs are not optimized for latency. . this optimization causes the BPD to keep its execution thread rather than releasing it back to the pool of threads that are shared between activities.Make sure that the number of requests for BPDs that have this optimization enabled that are sent to a cluster member per unit of time does not exceed the capacity of the execution threads that are available to process the requests. is scheduled by the Event Manager. . When enabled. This use of a pool of threads makes it possible for implementations of a BPD to run independently and in parallel. but performs a series of system tasks or decision tasks that are implemented by integration services. .Optimizing BPD execution for latency Select the optimization for latency to reduce thread context-switching for BPDs that require low latency responses. If the IBM BPM system is running under high load. the processing of an implementation of a specific process instance might be delayed because other work is already scheduled to be executed before it. You can change the optimizing setting for a BPD in Process Designer. About this task The execution of implementations of system tasks and decision tasks. this work might be run more efficient and with less latency by using a single thread on one cluster member. between activities. some types of BPD need higher performance to minimize the straight-through processing latency. open the Advanced section. Parent topic:Developing flexible and efficient process applications Related information: Maintaining and monitoring IBM Business Process Manager Event Manager 364 .Procedure To enable the optimization for latency. 1. 4. Open the BPD in the Designer view. On the Overview tab. 3. Select Optimize Execution for Latency to reduce thread context-switching for the BPD. complete the following actions. Clearing the option turns off the optimization for the BPD. Open the Process Designer desktop editor. 2. For example. Procedure 1. they must start the task from their task list. Before you begin To perform this task.When the second task in the sequence is a system task. set the assignment to be the last user: select Lane from the Assign To list and select Last User from the User Distribution list in the Assignments section of the properties for the activity.When an intermediate timer event or an intermediate message event follows the first activity in the sequence.If the elapsed time between the end of the first task and the arrival of the token at the next task is greater than the autoflow-timeout setting. .If the task is being tested in the Process Inspector. a customer service agent might be assigned a task for opening a new customer account that is followed immediately by a task for taking the new customer's order. then return to the task list for the next activity. 4. . you can designate that the coach for the second task opens immediately upon completion of the first task. if the owner of the first task is the same as the owner of the second task. you must be in the IBM® Process Designer desktop editor. By default. . To configure an activity to automatically start the following task. Open the BPD in the Designer view. the autoflow-timeout is set to 3 seconds. However. Instead of having the user return to his or her task list to retrieve the second task after the first one completes. About this task Normally. You can save users from having to go back to the task list when the next task in the process is also assigned to them. 365 . Open the Process Designer desktop editor. In the following task.Activities are still considered to be sequential even if they are separated by synchronous actions such as exclusive gateways or tracking points. 3. there are a number of scenarios where the second activity in a sequence cannot be automatically started even if the check box is selected on the first task: .xml file to modify the value of the autoflow-timeout setting.When the first activity flows to multiple tasks assigned to the same user. consider places in your process where you expect the same user to be completing multiple tasks in sequence. for example in a multi-instance loop or a parallel (split) gateway. You can use the 100custom. complete the work for that task. 2.Automatically starting the user's next task To help your business users be maximally efficient while they are using your application. In the Process Portal. the second task starts automatically when the first task is complete. . for each task that users are assigned. go to the Implementation tab of the first task in the sequence and select Automatically flow to next task. Parent topic:Developing flexible and efficient process applications Related information: The 99Local.xml configuration files 366 .xml and 100Custom. an order can be canceled before it has been sent out for delivery. The activity that calls the business process definition (BPD) should not be configured for looping. 6. 5. Open the BPD in the Designer view. To use ad-hoc tasks. and teams. Procedure To model a new activity or set of activities that a user can launch in the normal process flow. For information about security groups. Connect the task or tasks to the new start event. 4. business users can launch the set of activities from the action menu in the current application. Open the Process Designer desktop editor. you must be in the IBM® Process Designer desktop editor. but after it has been delivered. such as updating a customer's contact information or canceling the process instance. Before you begin To perform this task. the order can no longer be canceled. For example. 2. actions to be launched by the user from action menus in the Process Portal. if you are designing a process application where business users can look up a customer order history at any time in the normal processing of a customer order.0. To make an action available for only a certain phase of the process. see Configuring access to Process Portal action policies.Important: Ad hoc task instances that were created during the running of a process instance must be complete before the process instance completes. When you deploy your process application to the Process Portal. instead use Creating an unstructured (ad hoc) activity. 3. groups. complete the 367 . Process Portal users must be members of a security group that is configured for the ACTION_INJECT_TOKEN policy. you might include a set of tasks for logging into the order history database and submitting a query. For information about managing the security groups. complete the following steps: 1. see Creating and managing groups. or ad hoc.5. For information about the ACTION_INJECT_TOKEN configuration. New task instances are created and appear in the task list for the user or team that is assigned to the new ad hoc task. Restriction: Ad hoc start events are not supported in simple loop or multi-instance loop activities. see Setting up users.Defining ad hoc actions (deprecated) While a process is running. For example.5. Add the activity or set of activities that occur when the start event is triggered. Important: Ad hoc actions are deprecated in version 8. Optional: Ad hoc actions might be associated only with a particular phase of the process. a user might need to launch a new activity or set of activities. Add an ad hoc start event to your process diagram by dragging a start event from the palette and specifying an implementation type of Adhoc in the Implementation tab of the Properties view. The process designer can define a set of these unplanned. B.following steps: A. Add swimlanes to your BPD diagram and associate each swimlane with a specific team. For example. In the Event Visibility section. to restrict the visibility of the event by phase. to restrict the visibility of the event by swimlane select swimlane. C. select phase. To make an action available to only a certain team of users. you might have a pre-delivery phase that contains all the customer order activities that occur before the order ship. B. complete the following steps: A. Add phases to your BPD to define the different phases in the running process. For example. the ad hoc action is in the action menu only for users who belong to the specified team. 7. you might have a swimlane for customer service representatives and a swimlane for managers. C. Move the ad hoc start event to the swimlane that is associated with the team that should be able to launch the action in the Process Portal. you might want to limit a credit check override action to users who belong to the managers team. the ad hoc action is in the action menu only while the running process instance is in the specified phase. In the Process Portal. In the Process Portal. In the Event Visibility section. Parent topic:Developing flexible and efficient process applications Related information: Creating a team Deprecated: Enabling users to perform ad hoc actions 368 . and a post-delivery phase that contains the activities that occur after the order ships. For example. Optional: Limit the type of users that run ad hoc actions in your process. Move the ad hoc start event to the phase in which it should be available. you also can enable users to. Parent topic:Designing process interactions for business users 369 . and communicate through messages in the process activity stream.Enabling Sametime Connect integration for Process Portal You can enable instant messaging support to allow your end users to communicate in real time with others in the organization as they work on process activities. All of these features are available without any configuration of your process applications.Enabling IBM Connections integration for Process Portal If your environment is configured for IBM® Connections.Specifying experts for an activity Business users working with your process applications can collaborate or request assistance from expert users associated with a given task or activity. However. you can also enable users to chat with one another using Lotus Sametime Connect. . You can also specify a set of expert users for a given activity so that users can immediately identify the best person to ask for assistance in completing a task. With IBM Connections V4. users can request help from other users. receive notifications in IBM Connections when new tasks are assigned to them.Setting up collaboration features for business users Business Process Manager provides several features that allow business users to collaborate with other users while working with processes. collaborate in real time with other users on task completion. The list of experts appears in the Experts panel in the Process Portal environment. after they set preferences. you can set up Process Portal so that business card information displays when users click an avatar or a name. .0 or later. . About this task Within the Process Portal environment. You will need the Sametime Connect server location information in order to complete this task. In the Type field. If your setup is configured correctly. Procedure 1. Enter the information about your Sametime server.sthost . and then Add to add a new server. 5.The name of your Sametime Connect server. 4.jsp Where: . you must be logged into Process Designer with a user ID with administrative rights. . Test the connection to the Sametime Connect server. Ensure that your administrator has configured your Process Portal environment for IBM Lotus® Sametime® Connect integration. 3. users will be able to search for and chat with other users within the context of tasks and process activities. you will see the Lotus Sametime login window. 6. select IBM Sametime Server. Results While working with business processes in Process Portal. Open the process application in the Designer view.https://sthost:secureport/stwebclient/popup. 7. Parent topic:Setting up collaboration features for business users Related information: Configuring Sametime Connect integration 370 . Before you begin To perform this task. Point your browser to the following URL. you must be in the IBM® Process Designer desktop editor.Enabling Sametime Connect integration for Process Portal You can enable instant messaging support to allow your end users to communicate in real time with others in the organization as they work on process activities. Create a snapshot of the application. and install the snapshot on Process Server. 2. Open the Process Designer desktop editor.The port for the Sametime Connect server.To make changes to the Process Portal environment. Click the Servers tab.secureport . based on historical analysis. Open the BPD in the Designer view. . select the activity and go to the Assignments tab in the Properties view. 3. To explicitly specify an expert group for an activity. Before you begin To perform this task. 4. Parent topic:Setting up collaboration features for business users Related tasks: Configuring runtime teams Related information: Creating a team Getting help from experts to complete a task 371 .Users belonging to a team that is explicitly specified in Process Designer as an expert group for this activity. Open the Process Designer desktop editor. 2. Specify the relevant team in the Experts Team field. What to do next Your BPM administrator can configure the teams at run time to ensure that the correct set of users are identified as experts for the activity in Process Portal. An activity must be associated with a human service before it can be assigned experts. This list is limited to a small group of users who have completed the activity most frequently. If you have not already created a team that defines the experts for this task. you must be in the IBM® Process Designer desktop editor.Users who have completed this activity in the past.Specifying experts for an activity Business users working with your process applications can collaborate or request assistance from expert users associated with a given task or activity. you can create a new team to use. Procedure 1. The list of experts appears in the Experts panel in the Process Portal environment. About this task Each activity in Process Portal can list two types of experts: . Open the Process Portal application in IBM Process Designer. Procedure To enable the IBM Connections integration for Process Portal. which requires IBM Connections V4. In the Type field. Restriction: When coach views are displayed in IBM Connections.If you want users to see the IBM Connections avatar instead of the IBM BPM avatar. Specify whether the IBM Connections server uses Secure Sockets Layer (SSL). the user ID and password to IBM Connections are required to enable the IBM Connections server. you also can enable users to. Before you begin Ensure that IBM Connections is configured for your environment. To change the Process Portal application.0 or later.Enabling IBM Connections integration for Process Portal If your environment is configured for IBM® Connections. Provide a user ID and password. You need the IBM Connections server location information to complete this task. 5. 4. To modify the width of a coach view using the media type. complete the following steps: 1. 2. after they set preferences. select Use SSL 372 . If Process Portal is accessed through HTTPS. including the host name. see Configuring the Business Space Ajax proxy and Adding proxy policies to the Business Space Ajax proxy. do not select this setting. ensure that your administrator configured the IBM Connections integration. and you have IBM Connections V4 or later. and then click Add to add the IBM Connections server. you can set up Process Portal so that business card information displays when users click an avatar or a name. the proxyconfig. For information about updating the proxy configuration. 3. See Configuring IBM Connections integration for task notifications.xml file must contain a proxy policy for the URL of the IBM Connections server. click the Servers tab. log in to IBM Process Designer with a user ID with administrative rights.Tip: SSL is enabled by default in IBM BPM. so unless your administrator disabled SSL.Tip: If you want participants to use the IBM Connections notification capability. If you want users to receive activity notifications. select IBM Connections Server. select this setting. specifying a user ID and password is not required. see Defining coach view behavior. If Process Portal is accessed through HTTP. Complete the server locations information. the width is limited to 380 pixels. If your participants use only the business card capabilities. With IBM Connections V4. make sure that the user is a member of the trustedExternalApplication security role in the WidgetContainer application. On the administrative console for the IBM Connections server.0 or later. receive notifications in IBM Connections when new tasks are assigned to them. for IBM Connections. So that process participants receive notifications in IBM Connections. On the administrative consoles for your production systems. Process Portal users can see the business card information of the users whom they work with. Tip: The test does not include SSL certification. verify that the administrator exchanged SSL certificates between the IBM Connections server and IBM Business Process Manager as described in Configuring IBM Connections integration for task notifications. and install the snapshot on Process Server. If your setup is configured correctly. Results For IBM Process Server profiles. Parent topic:Setting up collaboration features for business users 373 . Create a snapshot of the application. This tests if the user ID and password successfully connect to the IBM Connections server. 6. make sure that the email addresses in their IBM Business Process Manager user profiles match the email addresses in their IBM Connections user profiles. ask them to update their user preferences as described in Setting preferences in Process Portal. What to do next For all Process Portal users. a message appears. the Process Portal snapshot is installed on IBM Process Server. Click Test Connection. 7. they can also act on individual process instances in the Gantt chart to resolve issues. Due dates are used in Process Portal to determine whether a process instance is on track for timely completion. Procedure 1. assign a group to the Expose Performance Metrics option. 3. About this task If the business process is enabled for process instance management. you must be in the IBM Process Designer desktop editor. If at-risk calculations are also enabled. At-risk calculations are based on the average time it takes to complete an instance of the process. Before you begin To perform this task. Enable due dates and at-risk calculations.Determine whether a running process instance is on track for completion. By default. each instance is due 8 hours after it is started. Open the Process Designer desktop editor. due dates are calculated from the creation time of the process instance based on the value of the Due in field and the settings for the work schedule.Change the due date of a running process instance. and 30 minutes. for example 2 days. Optional: Enable at-risk calculations. Grant users access to the Process Performance dashboard tab. Open the BPD in the Designer view. If the business process is enabled and process owners are authorized. If you select Days for the duration. Enable the due date.Without access to the tab. Set the expected duration of process instance in the Due in field. Due dates are shown for the instances of this process in Process Portal. To grant access.Adjust the due dates and durations of tasks in a process instance. .Enabling process instance management for a BPD In IBM® Process Portal. A. C. 4 hours. instances become at risk when the average time to completion is longer than the time left to the due date. process owners can use the Process Performance dashboard and the Gantt chart to complete the following tasks: . 374 . 4. such as bottlenecks.Due dates and at-risk calculations are enabled for a process by default in the Advanced section on the Overview tab. . At run time.View and change the projected path for a running instance. B. process owners can use the Process Performance dashboard to review the progress of processes and their instances. 2. users cannot see the Process Performance dashboard in Process Portal. on the Overview tab for the process. you can also add hours and minutes to the elapsed time. Process owners can modify the due dates in the Gantt chart. At-risk calculations require that the due date is enabled. . No future tasks .Gantt chart Gantt View page: . Optional: Enable the collection of historical data in the Performance Data Warehouse. If projected path management is not enabled. Results The Process Performance dashboards for processes and instances in Process Portal are enabled for process management. Send the updated tracking definitions to the Business Performance Data Warehouse.No estimated completion time .The projected path through the instance is based on the longest (pessimistic) path and not the typical historical path. A. If autotracking is not enabled. . Administrators can modify the set of users who are assigned to these policies.Projected path management is enabled for processes by default in the Advanced section on the Overview tab.ACTION_CHANGE_INSTANCE_DUEDATE The action policies are contained in the BPMActionPolicy configuration object. On the Overview tab. .ACTION_VIEW_CRITICAL_PATH . ensure that Enable tracking field is selected. the Gantt chart is affected in the following ways: .Historical data is used in the Set Path page of the Gantt chart to display the traversed path and calculate the projected path for a running process instance. timing intervals are sent to the Performance Data Warehouse and the Process Performance dashboard includes timing intervals on the Overview page. C. With projected path management enabled.ACTION_VIEW_PROCESS_DIAGRAM . or paths. What to do next 375 . B. Enable projected path management. the Process Performance dashboard and the Gantt chart are affected in the following ways: .ACTION_CHANGE_CRITICAL_PATH .Process Performance dashboard: No estimated completion time for entries in the Instances in progress list: . Important: The following Process Portal action policies determine who is authorized to view and change the projected path: .Historical path information is not available for the instance. ensure that Enable Autotracking is selected.Task durations are not editable 6. include tracking points in the process and create a timing interval to capture the time between the defined points.5. On the Tracking tab. If tracking points are defined for the process. the projected path for an instance can be displayed on the Gantt chart if distinct paths from the start to end nodes are found. Optional: Enable process owners to analyze the average amount of time that elapses between steps in the process.Gantt chart Set Path page: No projected path. There are several routes. that can be followed to complete a process. 7.To enable time lapses to be analyzed. Specifying activity due dates Activity due dates are used to calculate the expected completion time for an activity. . Parent topic:Designing process interactions for business users Related information: Configuring access to Process Portal action policies The Gantt chart Setting up autotracking Sending tracking definitions to Performance Data Warehouse Creating a timing interval for a business process 376 .Define the work schedule for the process and set the due date for individual activities.Setting the work schedule for a BPD The due date for a process instance is the expected date and time that all activities related to a process instance should be completed. The due date is affected by the work schedules of the users who receive the tasks involved in the process. This completion time is used during process execution to establish which tasks are overdue or at risk of being overdue. . If you use a String.xml configuration file in the following directory. the values are taken from corresponding settings in the 99Local. The TWWorkSchedule variable includes parameters for timeSchedule.The Time Schedule specifies the normal business hours that work can be completed. Tip: If you expect some activities to be completed by users with a specific work schedule. or if you leave the settings at use default. then IBM BPM assumes that the schedule is filled in appropriately. open them from the System Data toolkit.Timezone specifies the timezone that you want to apply to running instances of the current BPD. then IBM® BPM looks up the schedule by name according to those rules. Procedure In the Work Schedule section on the Overview tab. 9 AM to 5 PM. open it from the System Data toolkit. If you use the default values for any of these fields. specify the working hours that users are available to complete work. . timeZone. All standard time zones are available. . To view the parameters of the TWWorkSchedule variable.The Holiday Schedule is a list of dates that are exceptions to the normal time schedule. . For all of the work schedule values.You can also write an IBM BPM service to dynamically set the overall work schedule for a BPD and store the entire work schedule in the TWWorkSchedule variable. The due date is affected by the work schedules of the users who receive the tasks involved in the process. you can specify a different work schedule for that activity in the Properties view for that activity. you can select this schedule from the list. 377 . date calculations for instances of the BPD are based on the <default-work-schedule> in the configuration file. For example. About this task The default work schedule for all BPDs is specified in the 99Local.xml file. If you use one of the TWSchedule variables. where server_type is either processserver or process-center: PROFILE_HOME\config\cells\cell_name\nodes\ node_name\servers\server_name\server_type\config\system. To view the parameters of the TWTimeSchedule or TWHolidaySchedule variables. you can use a JavaScript expression with predefined variables. You can enter either a String (or String-generated JavaScript) or a JavaScript expression that returns a TWTimeSchedule or TWHolidaySchedule variable. and holidaySchedule. If you do not specify a work schedule for a BPD.Setting the work schedule for a BPD The due date for a process instance is the expected date and time that all activities related to a process instance should be completed. if you expect the users completing the task to be available Monday through Friday. After you add a new time or holiday schedule.xml configuration files 378 . or minutes..Examples You can specify a task Due in value in days.xml and 100Custom. You can set time and holiday schedules for activities on the Implementation tab. hours. Parent topic:Enabling process instance management for a BPD Related information: Using JavaScript variables and objects inside Process Designer The 99Local. it immediately becomes available in the time or holiday schedule list in the authoring environment. with an optional clock time.Managing time and holiday schedules You can manage time and holiday schedules by using the JavaScript API. . assume that the assigned time schedule for our sample task is Monday through Friday. this means 5 business days as available according to the time schedule. If you specify the task Due in value as 7200mins or 120hours. If you specify the task Due in value as 5 days (meaning 5 business days). If a holiday schedule is assigned. In our examples. hours. 2.Examples You can specify a task Due in value in days. this time is divided by 8 hours per business day. or minutes. In these examples. Parent topic:Setting the work schedule for a BPD 379 . which means that only 8 hours of work time are available on each business day. and if the assigned time schedule allows the days identified by the Holiday Schedule value to be excluded from the task due date calculation. 3. all Saturdays and Sundays are excluded. because each business day contains only 8 hours of available work time. If you specify the task Due in value as 24 hours. which means that more than 5 days might pass before the task is due. only 8 hours per business day can be worked on the task. the task due date moves even further out into the future. The calculated task due date therefore moves out into the future. this time schedule assignment has the following impact when it comes to the task due date calculation: 1. 4. because for every business day available identified by the time schedule. with an optional clock time. Depending on the task Due in value assignment. based on the time schedule. the task is allowed to take 3 days (meaning 3 business days). 9 AM to 5 PM. Managing time and holiday schedules You can manage time and holiday schedules by using the JavaScript API.Note: It might take some time for the new holiday schedule to be available in Process Designer after running the integration service. 5. The default schedules are specified in the 99Local.TWHolidaySchedule(). "yyyyMMdd").Date().dates[3] = new tw.dates[2] = new tw.dates[4] = new tw.Date().object. On the Implementation tab of the activity. 7.dates[3].Date(). "yyyyMMdd"). You can set time and holiday schedules for activities on the Implementation tab.object.Date(). "yyyyMMdd"). Run the BPD. holidaySchedule.arrayOf.parse("20100824".parse("20091231".dates[0].parse("20100308".name = "holidaySchedule" + new Date(). "yyyyMMdd").object. holidaySchedule.dates[1] = new tw. "yyyyMMdd"). 6.parse("20100501".object. and then set the time schedule to 7AM-7PM Every Day. select the holiday schedule that you created. holidaySchedule. restart Process Designer before you begin modeling. holidaySchedule.xml file.object. Create an integration service by using a server script similar to the following script:var holidaySchedule = new tw. Save the BPD.dates[5]. and then open the Process Inspector tab to verify the due date calculation. About this task Avoid removing the default holiday or time schedules. 4.object. Save and run the integration service. 2.object.Date(). Parent topic:Setting the work schedule for a BPD 380 . holidaySchedule. holidaySchedule. Changes to the default schedules require changes to the 99Local.Date(). 3. tw. After you add a new time or holiday schedule. Create a business process definition (BPD). holidaySchedule.dates = new tw.dates[0] = new tw.dates[2]. holidaySchedule.parse("20100223". holidaySchedule. "yyyyMMdd").addHolidaySchedule(holidaySchedule). To make use of your new holiday schedule right away.xml configuration file.dates[1]. holidaySchedule.dates[4]. Link the activity in a start-end flow. holidaySchedule. holidaySchedule. and add an activity with a default service.dates[5] = new tw. Procedure 1. holidaySchedule.object. holidaySchedule. it immediately becomes available in the time or holiday schedule list in the authoring environment.Date().system.parse("20100101".getTime(). and Holiday Schedule fields set to the default value: (use default). This completion time is used during process execution to establish which tasks are overdue or at risk of being overdue. select the time zone that you want to apply to the tasks that result from the current activity. then it is assumed that the holiday schedule is inserted appropriately. The working hours depend on the values that you specify for the time schedule. Timezone.You can leave the Time Schedule. specify values for the properties that affect the working hours that are available to complete work. In the other fields in the Priority Settings section.Specifying activity due dates Activity due dates are used to calculate the expected completion time for an activity. the time schedule. tasks are listed according to their due date status. time zone. If you use a JavaScript expression to define a holiday schedule that is specific to users who work on this task. . For example. 9 AM to 5 PM. you can also add hours and minutes to the elapsed time.The Holiday Schedule field contains a list of dates that are exceptions to the normal time schedule. About this task In IBM® Process Portal. if you expect the users who work on the task to be available Monday through Friday. To view the 381 . 2. then IBM BPM looks up the holiday schedule by name according to those rules. specify the expected duration of the activity in the Due In field. In the Priority Settings section. Procedure 1. Administrators can also change the default duration after deployment. time zone. see Setting the work schedule for a BPD. If you use the default values. If you use a String. For more information.In the Timezone field. You can modify this duration for each activity in your process. authorized business users can change the due date for individual tasks and the overall process instance in Process Portal.The Time Schedule field specifies the normal business hours. . For example. and holiday schedule that are specified for the business process definition (BPD) are used for the activity. Select an activity in the diagram and go to the Implementation tab of the Properties view. By default. If you select Days for the duration. 3. if you expect the users who work on the task to be in California. for example 2 days. and holiday schedule. The calculation of the activity due date is also affected by the working hours that users are available to complete work. you can select the US/Pacific time zone from the list. If you use a TWHolidaySchedule variable. the due date of a human task is 1 hour from the time of task creation. . and 30 minutes. If projected path management is enabled for the process. enter either a String (or String-generated JavaScript) or JavaScript that returns a TWHolidaySchedule variable. 4 hours. Activity due dates and the projected path are also used to calculate the expected completion time for a process instance. you can select this schedule from the list. parameters for the TWHolidaySchedule variable, go to the System Data toolkit and open the variable. What to do next If you plan to enable projected path management for the BPD, keep in mind that variable-based due dates used in the implementation of activities are not detected in the projected path. Parent topic:Enabling process instance management for a BPD Related information: Using JavaScript variables and objects inside Process Designer The 99Local.xml and 100Custom.xml configuration files 382 Generating names for process instances When you run a BPD, IBM® BPM creates a default name for the process instance. This name is visible to business users in the Process Portal, allowing them to distinguish between different instances of a process as they complete their work. In Process Designer, you can change the way the process instance names are generated for a BPD in the Process Portal. Before you begin To perform this task, you must be in the IBM Process Designer desktop editor. About this task By default, the name for each instance of a process is the BPD name plus the instance ID. The name for a given process instance is displayed in many different places in the Process Portal, including the users Work list, in the dashboards and in the details for all the tasks associated with the process instance. To modify the way that the process instance names for a given BPD are generated, complete the following steps. Procedure 1. Open the Process Designer desktop editor. 2. Open the BPD in the Designer view and go to the Overview tab. 3. In the Advanced section, change the text in the Instance name field if you want the name of each instance to be something other than the BPD name. Be sure to retain the quotation marks around the text. By default, the instance ID is appended to the instance name that you specify, using the tw.system.process.instanceId variable. You can remove this variable or use the variable picker to choose additional variables. 4. Save your changes. Parent topic:Designing process interactions for business users 383 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. - Tracking IBM Business Process Manager performance data To create customized and third-party reports in IBM BPM, you identify the data to track and send that data to the Performance Data Warehouse. - Sending tracking definitions to Performance Data Warehouse In order to track performance data, you need to send tracking definitions to the Performance Data Warehouse. Each time you update your tracking requirements in IBM Process Designer, you must send the updated definitions to Performance Data Warehouse. - Exposing performance scoreboards The performance scoreboards are not exposed by default. If you want to expose them to your Process Portal users, you must complete some manual steps. - Defining reports in Process Designer (deprecated) Reports enable you to analyze business data that is specific to your processes. You can specify the variables to track and define the report to query your tracked data. Users can view the resulting report scoreboards from the Dashboards page in Process Portal. Instead of using the deprecated reporting capabilities, consider using dashboards that you design in Coaches. Parent topic:Creating processes in IBM Process Designer Related information: Using IBM Business Monitor with process applications 384 Tracking IBM Business Process Manager performance data To create customized and third-party reports in IBM® BPM, you identify the data to track and send that data to the Performance Data Warehouse. To track data in a business process definition (BPD), use autotracking, tracking groups, or both. - Autotracking automatically captures data from tracking points at the entry and exit of each item in a BPD (for example, services, activities, and gateways). To enable autotracking, make sure that Enable Autotracking is selected under the Tracking tab of the BPD. (By default, the checkbox is not selected, which is better for performance.) Your system administrator can change this default. - Tracking groups provide more control over tracked data. For example, use tracking groups track a selected group of process variables across multiple BPDs or process applications and to store tracking points for a timing interval. To enable tracking groups, make sure that Enable Tracking is selected under the Overview tab of the BPD. (By default, the checkbox is selected.) Your system administrator can change this default. Note that the Enable Tracking setting does not apply to services with tracking points. Tracking data is always enabled when services contain tracking points. You can use both tracking methods in one BPD. If you use both autotracking and tracking groups, you can create a timing interval. After you configure data tracking for your BPD, and each time after that configuration that you update your data-tracking requirements, you must send the tracking definitions to the Performance Data Warehouse. When you send tracking definitions, either directly or as part of deploying a snapshot, the Performance Data Warehouse establishes the structure in its database to hold the data that Process Server generates when you run instances of your processes. In IBM BPM, these tracking requirements are called definitions because they establish the database schema in the Performance Data Warehouse to accommodate the tracked data that Process Server generates. When you change your tracking requirements in Process Designer, you must send the definitions to the Performance Data Warehouse. Therefore, you are developing process applications on Process Center Server, be sure to send definitions after you change each process application. For process applications that are deployed in runtime environments, create a snapshot of your changes and deploy the new snapshot to ensure that the data you want to collect is available in the runtime environment. - Data tracking considerations Before you implement data tracking in a process application, make sure you understand the supported data types and naming conventions, as well as any considerations for working with versioned data. - Autotracking IBM Business Process Manager performance data Use autotracking if you want to capture data to quickly configure and publish reports using the ad hoc wizard, or if you want to capture data that automatically includes tracking points at the entry and exit of each item in a BPD. For example, use autotracking if you know that you want to compare the duration for each 385 activity in a BPD. - Tracking groups of process variables Use tracking groups if you want to explicitly control your tracked data and tracking points. For example, you can group the variables that you want to track by type, strategically place tracking points in your BPD, and track variables across multiple BPDs. With tracking groups, your tracking points can also span multiple BPDs. - Creating a timing interval for a business process To enable process owners to analyze the amount of time that elapses between certain steps in a business process, you can add tracking points to the business process definition (BPD) and then create a timing interval to capture the duration between the defined start and end points. Parent topic:Enabling processes for tracking and reporting Related information: getBPMProperty command setBPMProperty command deleteBPMProperty command 386 Data tracking considerations Before you implement data tracking in a process application, make sure you understand the supported data types and naming conventions, as well as any considerations for working with versioned data. Supported data types Data types that IBM® BPM tracks include the following: Type of tracking Autotracking Tracking groups Supported data types String, Integer, Decimal, Boolean, and Date String, Number, and Date When you are tracking data, be aware of the following: - A tracking group can have a maximum of 50 fields for each of the data types. Do not increase the maximum number of fields because it can affect the database table size and future migration to a new IBM BPM release. - Variables for which the Is List option is enabled cannot be tracked. - Complex types cannot be mapped directly; their fields must be mapped individually. - Variables of type ANY, Map, Record, XMLDocument, XMLElement, and XMLNodeList cannot be tracked. Naming tracking groups When naming tracking groups and tracked fields, be aware of the following restrictions: - Do not use SQL-92 reserved words. Several sources available on the internet provide a complete list of SQL-92 reserved words. - Do not use any of the names used for the views and fields in the Business Performance Data Warehouse database schema. Tracking data across processes and process applications To track data from multiple processes (BPDs) that reside in the same process application, create a tracking group and implement it for as many BPDs as you like, mapping the tracked fields to the appropriate variables for each BPD. If you want to capture data from multiple processes (BPDs) that reside in different process applications, you can do so by using the same tracking group in each process application. For example, you can create a tracking group in a toolkit, and then create a dependency on that toolkit in each process application where you want to use the tracking group. From each process application, you can implement the tracking group one or more times, mapping the tracked fields to variables within each application. When you send tracking definitions and then run instances of the BPDs, the data is captured in a single tracking group view as described in "Business Performance Data Warehouse tracking group views." The data that IBM BPM captures enables you to analyze the tracked data in any way you choose. For example, you can analyze the tracked fields as a whole or you can compare the data from each process application or from each process. 387 Working with versioned data All data tracked by IBM BPM includes snapshot (version) information that enables you to create reports to compare versions of your processes if you have that requirement. When tracking data, keep the following in mind: - Timing intervals work across snapshots (versions). For example, a process that starts in one version (1.0) might be migrated to a new version (2.0) before reaching the end of a timing interval. In such a case, the data for the timing interval is captured in the Performance Data Warehouse as expected with the version change noted. - Data types of variables that are being stored (autotracked or part of a tracking group) can change between versions. If data types do change, a new column is created in the corresponding view as described in "Performance Data Warehouse database architecture." Parent topic:Tracking IBM Business Process Manager performance data Related information: Business Performance Data Warehouse tracking group views 388 Autotracking IBM Business Process Manager performance data Use autotracking if you want to capture data to quickly configure and publish reports using the ad hoc wizard, or if you want to capture data that automatically includes tracking points at the entry and exit of each item in a BPD. For example, use autotracking if you know that you want to compare the duration for each activity in a BPD. When you enable autotracking for a BPD, you also track the following Key Performance Indicators (KPIs) associated with your BPD. - Custom KPIs associated with your BPD - Custom KPIs associated with the activities in your BPD - The Total Time KPI associated with each BPD by default KPIs act as conditions for Service Level Agreements (SLAs), which you can use to trigger a particular consequence such as an email notification. You can analyze the performance of your SLAs using the SLA Overview dashboard that is available in Process Portal. To create custom SLA reports, use the SLASTATUS view and the SLATHRESHOLDTRAVERSALS view in the Business Performance Data Warehouse database. Autotracking is not required for the Process Performance and Team Performance dashboards, but some features of the Process Performance dashboard are not available without autotracking. For more information, see Enabling process instance management for a BPD. - Key performance indicators (KPIs) and service level agreements (SLAs) With the data that IBM Business Process Manager tracks and stores for key performance indicators (KPIs), you can analyze process performance and create service level agreements (SLAs). - Creating custom KPIs You can use key performance indicators (KPIs) to analyze process performance and create service level agreements. IBM Business Process Manager tracks KPI measurements at process run time and stores the information in the Business Data Warehouse. - Associating KPIs with activities To use a KPI in IBM Business Process Manager, you must associate it with one or several activities. - Creating SLAs Create service level agreements (SLAs) so that you can analyze the performance of your business processes over time. - Setting up autotracking You need to set up autotracking before you can use the ad hoc wizard. When autotracking is enabled for a business process definition (BPD), data for any nested processes of that BPD will also be tracked. Subprocesses and services inherit the setting of the parent process. Parent topic:Tracking IBM Business Process Manager performance data 389 390 Key performance indicators (KPIs) and service level agreements (SLAs) With the data that IBM® Business Process Manager tracks and stores for key performance indicators (KPIs), you can analyze process performance and create service level agreements (SLAs). KPIs Key performance indicators (KPIs) are measurements that IBM BPM tracks at process run time, storing results that you can use to analyze process and task performance in the Optimizer. IBM BPM includes the following types of KPIs: KPIs Standard KPIs Custom KPIs Description Located in the System Data Toolkit. By default, most of the standard KPIs are associated with each activity that you add to a BPD diagram. Click the KPIs option in the properties for an activity to see the associated KPIs. Each of these KPIs has default settings that you can change. You can define custom KPIs and associate them with one or more activities in your BPDs. When you run instances of a business process definition (BPD), IBM BPM tracks and stores data for configured KPIs in the Business Performance Data Warehouse. IBM BPM uses stored KPI data when you run certain types of historical analyses in the Optimizer. Not all historical analyses available in the Optimizer rely on data that is generated and stored because of KPIs. Note: The standard KPI, Total Time (Clock), is associated with each BPD by default. To view the settings for this KPI, click the Process KPIs tab in the Designer. You cannot alter the settings for this KPI. SLAs You can create service level agreements (SLAs) that are based on standard and custom KPIs. With SLAs, you establish a condition for one or more activities that triggers a consequence. For example, you can create an SLA that causes IBM BPM to send an email notification when a particular activity takes longer than expected to run. When you run instances of your processes, SLA consequences do not trigger until the associated activity starts or completes. For example, if you configure an SLA to send an email notification when a particular activity takes longer than two days to run, IBM BPM does not send the notification when the violation occurs. Instead, IBM BPM sends the notification when the activity is complete. Therefore, if the activity takes three days to complete, IBM BPM sends the notification then, informing users of the violation. With SLAs you can report violations and, over time, understand the trend in violations. To enable Process Portal users to immediately react to time-based conditions for 391 one activity, use a timer event to capture the violation. If an SLA is not based on time, consider using exposed process values (EPVs) to model the SLA. To provide immediate notification of violations, develop the appropriate implementation for your needs (such as a timer event for an escalation), and then create an SLA so that you can track and report historical trends. SLAs enable in-depth performance analysis over time, as described in the following table: Analysis My SLA Overview dashboard Custom SLA reports (deprecated) Historical analysis in the Optimizer view Description View this report in Process Portal to see the name, description, and status of each configured SLA, and a trend chart of violations for all SLAs or a specified SLA. The My SLA Overview dashboard is not exposed by default for Process Portal users. If you want process participants to see the My SLA Overview dashboard in their tabs list, you must expose it manually, as described in step 10 of Creating SLAs in Process Designer. Use SLA data that is stored in the Business Performance Data Warehouse to create custom reports using IBM BPM or a third-party tool. You can use the SLASTATUS and the SLATHRESHOLDTRAVERSALS database views to query the data.. When you are running scenarios, choose the SLA visualization mode to display results that are based on SLA violations. Parent topic:Autotracking IBM Business Process Manager performance data Related concepts: Business Monitor KPIs 392 Creating custom KPIs You can use key performance indicators (KPIs) to analyze process performance and create service level agreements. IBM® Business Process Manager tracks KPI measurements at process run time and stores the information in the Business Data Warehouse. Before you begin To perform this task, you must be in the IBM Process Designer desktop editor. About this task To create a custom KPI for IBM Business Process Manager, complete the following procedure. Procedure 1. Open the Process Designer desktop editor. 2. Open a process application in the Designer view. 3. Click the plus sign next to Performance and select Key Performance Indicator from the list. 4. In the New Key Performance Indicator window, type a descriptive name for the new KPI and click Finish. 5. Provide a description for the KPI in the Documentation field. 6. In the Details section of the window, select the Unit for the KPI from the dropdown list. For example, if your company assembles cell phones and you want to measure the number of phones in production, select Count from the drop-down list. 7. To roll up the unit you are tracking into a higher-level KPI, click Select to choose the KPI that you want. IBM Business Process Manager displays the KPIs in the current process application and any KPIs in referenced toolkits, including the System Data toolkit. For example, select the standard KPI, Resource Cost, to roll the Count KPI from the previous step into a higher-level KPI. You can click New to create a new KPI. Click the X icon to remove a roll-up KPI. 8. In the Roll-up multiplier field, specify the value by which to multiply the unit that you are tracking before the data is collected in the roll-up KPI. For example, to obtain an accurate Resource Cost for the previous step, enter the value of each cell phone in the Roll-up multiplier field. Rolling up to higher-level KPIs is useful when you create SLAs. The Resource Cost example in this procedure shows how to create an SLA for a condition where the cost of resources in production was either too high or too low. 9. Click Save. Parent topic:Autotracking IBM Business Process Manager performance data 393 Associating KPIs with activities To use a KPI in IBM® Business Process Manager, you must associate it with one or several activities. Before you begin To perform this task, you must be in the IBM Process Designer desktop editor. About this task Follow these steps to alter associated KPIs or associate a new KPI with an activity in a business process definition (BPD): Procedure 1. Open the Process Designer desktop editor. 2. Open the BPD in the Designer view. 3. Select the activity that you want to associate with a KPI and go to the KPIs tab in the Properties view. 4. To add a KPI, click Add and select the KPI or KPIs that you want. IBM Business Process Manager displays the KPIs in the current process application and any KPIs in referenced toolkits, including the System Data toolkit. 5. In the Assignment Settings panel, clear the Use KPI defaults check box if you do not want to use the default assignments for the selected KPI. A. Select the assignment type from the drop-down list. The assignment type establishes how the value for the KPI is determined. B. For KPIs that measure time, the assignment type is Automatic and cannot be changed. Automatic assignment means that IBM BPM automatically tracks and stores the values for these KPIs. C. For other KPIs, you can choose from the following assignment types: Assignment type Value per Hour (clock) Description Enables you to multiply the specified value times the total number of hours spent on the activity. Enables you to multiply the specified value times the number of working hours spent on the activity. Enables you to specify a value for the KPI. Enables you to supply custom scripts to track the value for this KPI. Enables you to specify the number of times an activity must be performed before it is considered rework. Value per Hour (calendar) Absolute Value Custom JavaScript True after N traversals (for Rework KPI only) 6. In the Threshold Settings area, clear the Use KPI defaults check box if you do not want to use the default threshold settings for the chosen KPI. If you do not use the default thresholds, you can indicate the type of performance that you 394 expect by providing minimum, expected, and maximum values in the appropriate fields. IBM BPM uses the specified thresholds as the range for producing heat maps and recommendations in the Optimizer. You can also use KPIs to specify conditions that trigger service level agreements (SLAs). 7. Click the Save icon in the toolbar to save your changes. Parent topic:Autotracking IBM Business Process Manager performance data 395 Creating SLAs Create service level agreements (SLAs) so that you can analyze the performance of your business processes over time. Before you begin To perform this task, you must be in the IBM® Process Designer desktop editor. About this task When you run instances of your processes, SLA consequences do not trigger until the associated activity starts or completes. With SLAs you can report violations and, over time, understand the trend in violations. Use other methods, such as timer events, to enable Process Portal users to immediately react to time-based conditions. The My SLA Overview dashboard is not exposed by default for Process Portal users. If you want process participants to see the My SLA Overview dashboard in their tabs list, you must expose it manually, as described in step 10 of the following procedure. Procedure 1. Open the Process Designer desktop editor. 2. Open a appropriate process application or toolkit in the Designer view. 3. Click the plus sign next to Decisions and select Service Level Agreement from the list. 4. In the New Service Level Agreement window, type a descriptive name for the new SLA and click Finish. 5. Describe the SLA in the Documentation field. 6. In the Trigger section of the window, the default trigger statement is displayed: Whenever the condition is violated. Complete the following steps: A. Click Whenever (displayed in blue font and underlined) to change the trigger for the SLA. For example, if you select Violated % of the time over period, the trigger statement changes to When the condition was violated 10% of the time over the last day. B. Click 10% of the time and set the percentage. C. Click last day and set the time frame. 7. In the Condition section of the window, the default condition statement is displayed: TheTotal Time (Clock) KPI for <select activities> is greater than 1 day. Complete the following steps: A. Click Single value and choose Single value, Sum of values over time, or Average value over time. B. Click Total Time (Clock) and choose the key performance indicator (KPI) that you want to use. C. Click <select activities> and choose the activities that you want to apply this SLA to. All activities are displayed under the BPD that they are in. 396 D. Click Greater than and choose greater than, less than, or equal to. E. Click 1 day and choose Threshold, % above threshold, % below threshold , Value above threshold, Value below threshold, or Value. Then, set more parameters as necessary. 8. In the Consequence section of the window, select the check box next to the action that you want to take when the specified condition is violated. A. To choose the Send email option, click <enter email address> and provide the address or addresses of the recipients of the notification. Separate addresses with a comma. B. To choose the Initiate process option, click <select process> and select a BPD. IBM Business Process Manager displays the BPDs in the current process application and any BPDs that are referred to in toolkits. The process that you run as a consequence of the violation must have the following input variables: Input variable violationRecord Type SLAViolationRecord parameters XMLElement Description Indicates which SLA was violated, to what degree, and when Reserved for future use 9. Click Select next to the Expose to view label and select the team whose members can view data for this SLA in the My SLA Overview dashboard in Process Portal. 10. Click the Save icon in the toolbar. 11. Expose the My SLA Overview dashboard so that it is available in Process Portal: A. In Process Designer, open the Process Portal application. B. Click Performance and then open PM SLA Overview. C. In the Exposing section, click Select next to the Exposed to field to choose the team whose members can view and use the My SLA Overview dashboard. To create a team, click New. To remove an assigned team, click the X icon next to the Exposed to field. D. Save your changes. 12. Test the SLA in the My SLA Overview dashboard in Process Portal. If the dashboard does not display any data, complete one of the following steps: - In the Process Portal application, select Implementation > Periodic SLA Update, and click Run now. - Include the Update All SLA Statuses service from the system toolkit in a process application, and run the process application in Process Portal before you test your SLA. Parent topic:Autotracking IBM Business Process Manager performance data 397 Setting up autotracking You need to set up autotracking before you can use the ad hoc wizard. When autotracking is enabled for a business process definition (BPD), data for any nested processes of that BPD will also be tracked. Subprocesses and services inherit the setting of the parent process. Before you begin To perform this task, you must be in the IBM® Process Designer desktop editor. About this task To use autotracking, perform the following steps. Procedure 1. Open the Process Designer desktop editor. 2. Open the BPD in the Designer view. 3. Click the Tracking tab for the BPD. 4. Ensure Enable Autotracking is selected. 5. In the Autotracking Name field, enter the name you want to use. 6. In order to analyze process data according to particular business variable values, set the variables as follows. A. Click the Variables tab for the diagram. B. For each variable you want to track, right click it and then click Track this Variable. 7. Save your changes. 8. Click File > Update tracking definitions to send the new tracking requirements to the Business Performance Data Warehouse. Results When you run instances of the process, IBM Business Process Manager stores the tracked data for each variable in the appropriate column. Each row in a Tracking Group view represents a discrete unit of tracked data. Parent topic:Autotracking IBM Business Process Manager performance data 398 Tracking groups of process variables Use tracking groups if you want to explicitly control your tracked data and tracking points. For example, you can group the variables that you want to track by type, strategically place tracking points in your BPD, and track variables across multiple BPDs. With tracking groups, your tracking points can also span multiple BPDs. About this task Tracking groups provide the following advantages: - You can group similar data together for analysis. For example, you can track employee data, account data, or shipment status information in independent tracking groups. - You can track process variables across multiple BPDs and process applications. For example, if your organization includes several locations and each location has a similar, but unique, onboarding process for new employees, you can create a tracking group to capture the business data for all of these processes. - Tracking points for a timing interval can span multiple BPDs. For example, if you want to measure the duration between steps that start in one process and end in a nested process, you can include the start tracking point in the main process and the end tracking point in the nested process. - Creating a tracking group Create and use a tracking group to track process variables across multiple business process definitions and process applications, or to store tracking points for a timing interval. Use tracking groups when you want to explicitly control your tracked data and tracking points for more advanced custom reports. - Associating process variables to a tracking group You can associate process variables to a tracking group in order to track them. Parent topic:Tracking IBM Business Process Manager performance data 399 In the Tracked Field Details panel. and send the tracking information to the Business Performance Data Warehouse. 7. you must be in the IBM® Process Designer desktop editor. 9. and Date/Time. Click Finish. For each tracking event. A. Number. enter a name for the tracking group. When prompted. Parent topic:Tracking groups of process variables 400 . C. The Tracking Group window opens in Process Designer. Before you begin To perform this task. Open the business process definition and add one or more tracking events to the diagram. 4. Procedure 1. Open the Process Designer desktop editor. Click the plus sign next to the Performance category in the library. 2. click File > Update Tracking Definitions . 8. Click Add in the Tracked Fields panel to add the field. 6. Open a process application in the Designer view. add a field to the tracking group. or to store tracking points for a timing interval. 5. Use tracking groups when you want to explicitly control your tracked data and tracking points for more advanced custom reports. assign tracking events to it. 10. For each process variable you want to track. About this task Use the Process Designer to create a tracking group. Add the process variables that you want to associate with each tracked field. What to do next Associate process variables with each tracked field in the tracking group.Creating a tracking group Create and use a tracking group to track process variables across multiple business process definitions and process applications. and then click Tracking Group from the list of components. To send the new tracking information to the Business Performance Data Warehouse. Save the business process definition. 11. specify the name and type for the process variable. Attention: A tracking group can have a maximum of 50 fields for each of the data types String. In the New Tracking Group window. B. 3. The new field is added with the default name UntitledNumber (string). select it and open the Implementation tab. save the changes. You can also include documentation. To perform this task. 8. Click Select and select the tracking group you want to use. 2. Open the Process Designer desktop editor. Select the check box of each tracked field you want to use and click the selection icon ( ) to bind a process variable to it.Associating process variables to a tracking group You can associate process variables to a tracking group in order to track them. 3. Click File > Update Tracking Definitions to send the new tracking information to the Business Performance Data Warehouse. Procedure 1. This new view displays the values of each variable associated to the tracking group. you automatically created a view in the Business Performance Data Warehouse database. Open the business process definition (BPD) in the Designer view. you must be in the IBM® Process Designer desktop editor. Parent topic:Tracking groups of process variables 401 . About this task After you create a tracking group. 7. Select the tracking event and open the Implementation tab. 4. 6. Add a tracking event to your BPD. Results By updating tracking definitions. use the following steps to associate process variables with each tracked field in the tracking group. Before you begin You must create a tracking group to hold the process variable data that you want to track. 5. Save your changes. process owners can use the Process Performance dashboard in Process Portal to calculate the duration of a process. Save your changes. select the Add button in the Start Points and End Points panels. for example. Before you begin Do the following tasks before creating a timing interval: .Add tracking points to the BPD . and then click Timing Interval from the list of components. About this task When you create a timing interval for the process. select the Calculation Bound list in the Start Points and End Points panels.Creating a timing interval for a business process To enable process owners to analyze the amount of time that elapses between certain steps in a business process. you can add tracking points to the business process definition (BPD) and then create a timing interval to capture the duration between the defined start and end points. and then click Finish.Enable autotracking . Define the timing interval. B. C. 5. Parent topic:Tracking IBM Business Process Manager performance data Related information: Deprecated: Defining reports in Process Designer 402 . Ensure that you add each tracking point to the tracking group that you create. To indicate the binding calculation you want to use for the start and end points in the interval.Open the IBM® Process Designer desktop editor. expand Performance by clicking the plus icon. 4. In the Designer library. . 2. To add the start and end points for the timing interval. Results Timing intervals are available in the Overview page of the Process Performance dashboard in Process Portal. TimeToCompleteRequest. The Timing Interval window opens in Process Designer.Create a tracking group to hold the timing interval data. A. Procedure 1. Type the timing interval name in the Name field. Open the Process Designer desktop editor. 3. Open a process application that contains a BPD. or compare the duration of several processes. 403 . Each time you update your tracking requirements in IBM® Process Designer. be sure to send definitions when you make changes. If IBM Business Monitor is installed. you must send these tracking requirements to the Performance Data Warehouse if you plan to run your processes on the Process Center Server to test data tracking and reports. its tracking definitions (part of a monitor model) are updated when you use this menu item. For process applications deployed in runtime environments. manually create or edit tracking groups. or perform any other task in the Designer in IBM Process Designer to capture performance data. About this task When developing on the Process Center Server. you must send the updated definitions to Performance Data Warehouse. snapshot any changes and deploy the new snapshot to ensure that the data you want to collect is available in the runtime environment.Sending tracking definitions to Performance Data Warehouse In order to track performance data. 404 How to send tracking definitions In Process Designer. Server Description Process Center Server When you use autotracking. . The method of sending tracking definitions varies depending on the type of server you are using. you need to send tracking definitions to the Performance Data Warehouse. click File > Update Tracking Definitions. Process servers in runtime When you deploy environments snapshots of process applications on process servers in runtime environments. you can select the Update Tracking Definitions option for the snapshot in the Process Admin Console. these tracking requirements are called definitions because they establish the database schema in the Performance Data Warehouse to accommodate the tracked data generated by the Process Server. There is no need to send tracking definitions unless a problem occurs during snapshot deployment. all tracking definitions are automatically sent to the Performance Data Warehouse in the selected runtime environment. If IBM Business Monitor is installed. its tracking definitions (part of a monitor model) are automatically updated as well. Parent topic:Enabling processes for tracking and reporting 405 . either directly or as part of a snapshot deployment. This ensures that your data is tracked as expected when instances of your processes are run in the runtime environment. Results When you send tracking definitions. In IBM BPM. If a problem does occur. the Performance Data Warehouse establishes the structure in its database to hold the data that is generated by the Process Server when you run instances of your processes. complete the following steps: 1. click the X icon next to the Exposed to field. To create a team. In the Exposing section. you must complete some manual steps.Exposing performance scoreboards The performance scoreboards are not exposed by default. Before you begin To perform this task. 2. Procedure If you want to expose a performance scoreboard to your Process Portal users. Parent topic:Enabling processes for tracking and reporting 406 . If you want to expose them to your Process Portal users. Click Performance and then open the scoreboard. Open the Process Designer desktop editor. Open the process application. The scoreboard is available in the Process Portal Organize tabs list for the members of the team that it is exposed to. 4. 3. click Select next to the Exposed to field to choose the team whose members can view and use the scoreboard. Save your changes. 5. you must be in the IBM® Process Designer desktop editor. To remove an assigned team. click New. You can also specify a time period filter and a business data filter. by default it is not enabled. expand Performance. In the Scoreboard window in the Reports section. Click the Refresh icon to preview the chart. and select ScoreBoard from the list of components.Defining reports in Process Designer (deprecated) Reports enable you to analyze business data that is specific to your processes. B. and enable the Backward Compatibility capabilities. Instead of using the deprecated reporting capabilities. 407 . give the dashboard a name. 2. In the Create Report window. This title is what Process Portal users see in the list of dashboards. and click Finish. A. In the library for the BPD. in Process Designer go to File > Preferences > IBM BPM > Capabilities. 7. Define the content of the report. 8. click Select next to the Exposed to field. Open the Process Designer desktop editor. select the Enabled check box. and then the report. you must be in the IBM Process Designer desktop editor. In the New Scoreboard window. click the Create Report from Chart button. Procedure 1. Results When you log in to Process Portal as a member of a team to whom the dashboard is exposed. Users can view the resulting report scoreboards from the Dashboards page in Process Portal. B. and select the team whose members can view this dashboard in Process Portal. A. 9. and type a title in the ScoreBoard title field. Create the scoreboard to display the report. Assign the report to the dashboard. When you are satisfied with the appearance of the chart and the data. Click File > Ad Hoc Report Analysis. Click the dashboard to display the report. Ensure that the tracked data is current by selecting File > Update tracking definitions. C. Ensure that autotracking is enabled for the business process definition (BPD). consider using dashboards that you design in Coaches. and click Finish. give the report a name. In the Layout section. you can see the new dashboard in the list of dashboards. Open the process application. To enable reporting. 3. Select the variables for the X and Y axes from the corresponding bindings lists. 5. Before you begin The reporting functionality is deprecated in IBM® BPM V8. 4. You can specify the variables to track and define the report to query your tracked data. click Add. In the Exposing section. 6. To perform this task. select a layout. Defining a custom layout Process Designer for reports (deprecated) When you define a report in Process Designer. you can select an existing chart layout (for example. to display resulting data. one of the layout included in the System Data toolkit). or you can create a custom layout. you can adjust the members of the team to whom the dashboard is exposed. . Parent topic:Enabling processes for tracking and reporting Related tasks: Configuring runtime teams 408 .What to do next After installing a process application snapshot that includes the dashboard. the Chart Definition text box includes the CSS framework for a new definition to help you get started. the chart types available by default in the System Data Toolkit may not meet the needs of your users. 3. In the New Chart Type window. Parent topic:Defining reports in Process Designer (deprecated) 409 . and enable the Backward Compatibility capabilities. you must be in the IBM® Process Designer desktop editor.Defining a custom layout Process Designer for reports (deprecated) When you define a report in Process Designer. 2. If not. Optionally provide information about the new chart type in the Documentation text box. 8. Or. You can use the framework to build a definition for the new chart type or you can overwrite the framework by copying and pasting an entire CSS definition from another application like IBM ILOG JViews Charts. Click Preview to ensure that the CSS definition produces the chart layout that you expect. By default. or you can create a custom layout. by default it is not enabled. Open the Process Designer desktop editor. Creating a custom chart type enables you to control the format of your report results. About this task The reporting functionality is deprecated in IBM BPM V8. Before you begin To perform this task. 6. Click Save in the main Process Designer toolbar to save the custom layout. you may want to develop customized chart types to meet corporate guidelines. Procedure To create a custom chart type: 1. to display resulting data. you can select an existing chart layout (for example. For example. 4. enter a name for the chart type and click the Finish button. Open the process application. 7. in Process Designer go to File > Preferences > IBM BPM > Capabilities. enter the Cascading Style Sheet (CSS) definition for your custom chart type. Click the plus sign next to the All category in the library and select Chart Type from the list of components. one of the layout included in the System Data toolkit). refine the definition until it meets your needs. To enable reporting. 5. In the Chart Definition text box. To create a case. you create the user interface that case workers see in Process Portal. You also identify the conditions that are required to start and complete the case and activities. You identify the documents that are used and the teams of users that work on the activities.Building cases A case is a project that starts and finishes over time to resolve a problem. Case management functions are only available if you have IBM BPM Advanced with the Basic Case Management feature installed. It also provides a graphical user interface for case workers to manage cases. For example. Finally. These people often have a relationship to each other. you design 410 . With IBM Business Process Manager. The following diagram illustrates the main tasks and activities that are associated with building a case. - Case management overview IBM Business Process Manager is a case management system that simplifies the job of designing and building cases. A case usually involves multiple people from inside and outside of an organization. you identify the user activities that are needed to complete the case and then group those activities into a case. 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 customer with a problem and a corporate support representative who solves the problem for the customer. Testing and debugging a case type Play back your case type in the Inspector to test and debug your activities. which can do standard tasks in your case management applications. The IBM BPM content store supports all Content Management Interoperability Services (CMIS) operations and most inbound events and you can use either Coaches or Heritage Coaches to work with IBM BPM documents in the content store. A case type also uses document types that define the documents that are required for the case. As you identify the content that is needed to complete the activities. These services. decide who works on the content. consider what does or does not need to happen to complete an activity. At run time. Creating a case type A case type defines the activities that are needed to resolve a specific business problem.5. A case type also defines who works on these activities and the steps they take to resolve the problem. The IBM BPM content store The IBM BPM content store is a CMIS-enabled embedded document repository that is used to store IBM BPM documents in IBM Business Process Manager Advanced version 8. Case workers can then complete work items that are associated with cases. and also define the order in which activities are performed by setting preconditions. It supplants the document attachment feature that was used in earlier releases. Designing a case To design a case management application.a case management application that is based on closely related cases and then deploy that solution into a production environment. can be shared by all case types in a process application. Decide what business level activities and steps you need. and add implementation logic. You add an activity in a case type and classify it as either is required or optional. You can configure a case to start when a document of a specified document type is filed into the IBM BPM content store. Document types provide order to the many kinds of documents that can occur in a case. Services to support case management applications You can create services to use with your case management applications. identify what user activities are needed to accomplish the main user goal. Creating a document type Document types classify the documents that belong to a case. Adding a case activity An activity in a case is a discrete task that can be completed by a person or a system as part of that case. which is an instance of a case type. Then. Typically a case has a number of activities. and then group those activities and steps into a case. 411 . Opening Case Designer from Process Center You can configure process applications and toolkits so that users can open them in Case Designer from Process Center. a business user works with a case. You can also set a precondition on an activity to start the activity when a document of a specified document type is filed in the IBM BPM content store Creating case user interfaces Create user interfaces that a user sees for the case instance in Process Portal.5.0 or later. Parent topic:Building process applications 412 .- Case artifacts and the IBM BPM content store The IBM BPM content store contains the generated case folder and document definitions and the case artifacts. and other components. Case workers can then complete work items that are associated with cases. A case management application is an application that case workers use to process cases. For example. Scenario: Financial services credit card dispute resolution IBM Business Process Manager can provide card-issuing banks with a case management application for credit card dispute resolution.Enterprise Content Management integration that includes complete document lifecycle capabilities. It also provides a graphical user interface for case workers to manage cases. - Case management concepts Case management applications consist of case types. and people by providing you with the following functions: .Case management overview IBM® Business Process Manager is a case management system that simplifies the job of designing and building cases.True content management functions to store document metadata that you can modify and search on. With IBM Business Process Manager.An active-content infrastructure that manages the persisted case object model and enables content-based events for case activities. . you design a case management application that is based on closely related cases and then deploy that solution into a production environment. processes. The business analyst can quickly process any 413 . It improves case worker efficiency and reduces the chance for errors as the case is being processed. Scenario: Automobile insurance claims IBM Business Process Manager can provide an application for creating and managing automobile insurance claims. These capabilities include creating a version and security. Some licensing restrictions might apply. 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 to design and create an application that case workers can then use to process the cases that are created. For example. . You can use the user interface to create a team-based experience that provides case workers with the information they must work on. the addition of a document or a field change triggers a case activity. A transcript of the video is available. With the case management system. if you want to design an application for resolving credit card disputes. IBM Business Process Manager provides a comprehensive view of the case for the case workers. watch this short overview video available on YouTube or in the IBM Education Assistant information center. . you can associate the data about the claim and the submitter with the supporting documentation as it is submitted.A process that manages the logic for running a sequence of activities. . For a high-level overview of how IBM Business Process Manager handles cases. IBM Business Process Manager unifies information.An out of the box user interface that is flexible and customizable. human services. document types. By configuring an application in IBM Business Process Manager. you can ensure that claims are processed completely and accurately. Parent topic: Building cases Related concepts: Designing a case application Related tasks: Creating a process application for your case types Creating a case type Creating a document type Related reference: Services to support case management applications 414 .required changes to the automobile claim solution. The process application might also include a case type for retirement and a case type for employee termination.Process application .Case management concepts Case management applications consist of case types. You can provide more information about the documents by assigning properties to the document type. The case type also includes properties that are shown to case workers in Process Portal. You can use preconditions to determine process routing. A precondition determines the action to take if particular conditions are met in a case. Case types also specify the teams that must complete the activities to solve a business problem. . . Case management functions are only available if you have IBM BPM Advanced with the Basic Case Management feature installed. and routing to the case workers. a document type might be a job application form. For example. Case types make up a case management application.Case types define the activities and might use document types to support the activity. 415 . A case management application is an application that case workers use to process cases.A process application contains one or more related case types that provide the documents. For example. document types. a process application for a human resources department might include a case type for new hires. .A case type can contain preconditions.Document types . data.Document types help you to organize and classify the documents that belong to a case.Preconditions . human services. and other components. . business processing.Case types . A case is an instance of a case type. - Coaches - You can define a launch user interface or an instance user interface for a business user to work with your case. The implementation of these user interfaces by a client-side human service can contain coaches. Human services with coaches can also be used to implement activities. - Activities - A case contains activities. An activity in a case is a discrete task that can be completed by a person or a system as part of that case. You can implement an activity as a user task, which is a client-side human service, a subprocess, or a linked process. For example, an activity might be to review new hire applications. A case is not complete until all activities that are marked as required during design are completed. Also, all activities that are started must be completed. For details about the states that an activity can be in, see Runtime states for activities in process applications. - Linked process - A case can call a reusable process, which is known as a linked process. Since a linked process is reusable, it can be used by many cases. For example, creating a customer account might follow a common set of steps; so, if created with a linked process, it might be used by many cases. - Subprocess - A subprocess is an option for encapsulating logically related steps within a case. Steps in a subprocess can directly access variables from the case. No data mapping is required. However, unlike a linked process, a subprocess can be accessed and instantiated only from the case that is using it. It is not reusable by any other case. - Client-side human services - Human services are the human actions in a process that must be completed for an activity. For example, a human service might be to review a job application form. There are two types of human services in IBM BPM; heritage human services, and client-side human services. Case activities use client-side human services. Use the Client-side human service editor to create and edit human services. - Teams - A team represents a specific business function. For example, a team might be an Applicant or Supervisor. You assign users and groups to teams. You can assign them at design time with the Designer or at run time with the Process Admin Console. Teams are associated with cases. You can also specify which users can start a case. Parent topic: Case management overview Related concepts: Scenario: Financial services credit card dispute resolution Scenario: Automobile insurance claims 416 Related information: Business process management and case management Client-side human services 417 Scenario: Financial services credit card dispute resolution IBM® Business Process Manager can provide card-issuing banks with a case management application for credit card dispute resolution. IBM Business Process Manager provides a comprehensive view of the case for the case workers. It improves case worker efficiency and reduces the chance for errors as the case is being processed. Case management functions are only available if you have IBM BPM Advanced with the Basic Case Management feature installed. Problem Banks that issue credit cards are seeing a significant increase in dispute cases. In addition, regulatory reform and an increased focus on customer satisfaction put more pressure on banks to handle each case as efficiently as possible. The banks require a solution that enables them to process each incoming dispute and decide whether to forward it to the credit card company for chargeback. Credit card companies have strict requirements for how cases can be submitted. The bank solution must provide accurate and appropriate information to the credit card company to ensure efficient processing. Solution to problem A business analyst at the bank, Anna, studies the requirements of the credit card company's dispute process. Anna determines the types of information that the credit card company requires to process a dispute. Anna uses the IBM Business Process Manager tools to quickly design and create an application. The application helps the bank representatives capture all of the required information in a case and attach extra records and documents to the case. Anna determines what teams must be involved in processing dispute and fraud cases, and Anna assigns permissions to different groups based on those teams. Scenario Jane, a credit card customer of the bank, buys a table from an online merchant for $400. The table is not delivered within three weeks as the merchant promised. Jane sends email and calls the merchant. However, no one responds. Because Jane used a credit card for the transaction, Jane calls the bank for help. Jane enters the account information by using the automated phone system. As a result, the call is routed to Nicole, a senior customer service representative. When Jane explains the situation, Nicole opens a case to track the dispute. Nicole finds the purchase transaction for the table from Jane's account and adds the record to the new case. Nicole forwards the call and the case to a dispute agent, Frank. During the conversation with Jane, Frank enters data into the case by using a form that captures details about the transaction, the merchant, and the customer. Jane says that a copy of the receipt can be provided and a copy of the delivery agreement. Frank creates an activity in the case to follow up on requesting the documents. Frank tells Jane that an investigation is proceeding, and adds Jane's preferred contact method to the case. When the call ends, a recording of the call 418 is automatically added to the case as a document. Frank uses Process Portal as an interface. This interface is customized to Frank's job as a case worker. The interface provides a comprehensive view of the case. The tools to review details of the case are readily available and actions can be taken based on the findings. After some research, Frank discovers that the merchant is out of business. Frank adds a comment to the case about this discovery. Frank is notified that the online receipt and delivery agreement from Jane are available. These documents automatically get added to the case and are ready for Frank to review. Frank decides to process a chargeback against the merchant. Frank starts an activity that gathers the relevant details of the case. The activity formulates the chargeback request, validates that the information is correct and complete, and forwards it to the credit card company. Frank also creates an activity in the case for Frank's supervisor Richard to review the case. Richard can then determine whether any action must be taken based on the fact that the merchant is no longer in business. Frank's supervisor Richard reviews the case. Richard notices Frank's comment that the merchant is out of business. Richard also analyzes recent transactions that involve the merchant to determine the bank's level of exposure. Based on this analysis, Richard decides to set up a subteam to handle any disputes that involve this merchant. Richard sends a change request to Anna, who is the business analyst, to modify the application to incorporate this new team. From Richard's Process Portal environment, Richard requests that a letter is sent to affected customers to inform them of their dispute rights. Richard also sends an alert to the team of advisors to inform them of the situation. Richard then completes the review of the case. Anna receives Richard's change request. To satisfy the new requirement, Anna designs a new team for the subteam in the application and a new rule. When customers call with disputes that involve this merchant, the new rule routes the disputes to the new team. By using the IBM Business Process Manager tools, Anna can implement the changes in a few minutes. Anna can then easily test the changes before Anna deploys the changes to the production system. Because the credit card company implemented an efficient case management process, Jane's and other customer's requests can be more quickly resolved. Parent topic: Case management overview Related concepts: Case management concepts 419 Scenario: Automobile insurance claims IBM® Business Process Manager can provide an application for creating and managing automobile insurance claims. With the case management system, you can associate the data about the claim and the submitter with the supporting documentation as it is submitted. The business analyst can quickly process any required changes to the automobile claim solution. By configuring an application in IBM Business Process Manager, you can ensure that claims are processed completely and accurately. Case management functions are only available if you have IBM BPM Advanced with the Basic Case Management feature installed. Problem Automobile insurance claims can involve input and supporting documentation from many sources. The sources include the claim submitter, the repair shop, the police, and other official sources of information about vehicle value or road conditions. In addition, different analysts are often required to evaluate and add information to an insurance claim during processing. All documentation and claim information must be available and easily accessible to enable adjustors to properly evaluate and resolve the claim. Individual claims can vary greatly. This variability can require case workers to start discretionary processes and to involve new teams. The variability can also change how and when tasks are completed as the claim is routed through the organization. Solution to problem Javier, a business analyst at the automobile insurance company, is working on making the automobile claims process more consistent. Javier uses IBM Business Process Manager to design an application with activities that involve multiple human services. Javier creates teams for each step in the claims process. Javier assigns permission to the teams for the groups of employees who do the activities at each stage in the process. The application that Javier designs combines these elements. - Claim properties, such as policy number and accident details - Teams, such as claims adjustor or fraud investigator - Case types, such as general claims, claims with injury, or major loss claims. In addition, IBM Business Process Manager enables Javier to create a flexible solution. Javier can quickly change teams, processing, or add activities when they are needed. Scenario Carly is driving on a roadway when Carly's car strikes a large object. Although Carly is not hurt, the car is too damaged to drive. The police arrive, and a tow truck is dispatched. When Carly calls the insurance company, customer service representative Chris opens a case for the claim. Chris uses a First Notice of Loss (FNOL) form to record the information. When Chris enters Carly's home phone 420 number, many of the form fields are automatically populated with data that is retrieved from the system. Chris asks about Carly's location, and tells Carly to have the tow truck driver take the damaged car to a specific nearby repair shop. The case information is forwarded to the car repair shop. Chris tells Carly how to use a PDF form that is available on the insurance company's website to provide details about the accident. Chris gives Carly the case number that was generated when Chris opened Carly's case. Carly is told to include the case number on the form. Chris recalls a memorandum about recent fraudulent claims that involve collisions with roadway debris. Chris creates a discretionary task to involve a fraud investigator in the claim. Later, Carly downloads the PDF form from the insurance company's website and enters the accident details and the case number. Carly mails the form back to the insurance company. Because this action is set as a precondition on Chris's task to review the claim, Chris is notified when the form is added to the case. Also, on the company website, Carly uses the case number to access a tool for uploading photographs of the damaged car. John, the agent at the car repair shop, receives notification about the case. John creates a task to provide an estimate for repairs. John makes sure that the $4500 estimate for repair does not exceed the value of the car and submits the estimate to the insurance company. John uses Carly's contact information to notify Carly that the estimate was submitted. The case is routed to Lisa, an adjustor. Lisa reviews the case and the supporting documents, including the police report and the photographs of the damage. The estimate is below the threshold for investigation, and the fraud investigator set the flag for possible fraud to false. Lisa approves the claim. After the case is closed, the insurance company receives a report from the police. The report says that a freight company was charged with dropping the object that caused Carly's accident. Lisa reopens Carly's case. Lisa contacts Javier, who adds a team to the system called recovery expert. The recovery expert creates new tasks to attempt to reclaim the cost of the repairs from the freight company. Because of the flexibility of this case management system, case workers can resolve problems more quickly and efficiently, and customers can close their claims more easily. Parent topic: Case management overview Related concepts: Case management concepts Scenario: Financial services credit card dispute resolution 421 Designing a case To design a case management application, identify what user activities are needed to accomplish the main user goal. Decide what business level activities and steps you need, and then group those activities and steps into a case. As you identify the content that is needed to complete the activities, decide who works on the content. Then, consider what does or does not need to happen to complete an activity. Case management functions are only available if you have IBM BPM Advanced with the Basic Case Management feature installed. One approach to designing an application is to first identify the types of documents that people in your organization must complete for some activity. For example, to resolve a credit card dispute claim, you might need a dispute form and a customer to complete the form. Then, a service representative must review that form. Next, you might initiate a fraud investigation if the circumstances warrant such an activity. In that case, you might need a fraud investigator to review the claim. Therefore, for a credit card dispute case, the application must include these artifacts: - Dispute form - Fraud investigation form Your application must also include these teams: - Customer - Customer service representative - Fraud investigator You can use the Case Type editor to help you think through the various document types, teams, case types, and activities that you need. Parent topic: Building cases Related concepts: Case management overview Related tasks: Creating a process application for your case types Creating a case type Creating a document type Related reference: Services to support case management applications 422 Center Opening Case Designer from Process You can configure process applications and toolkits so that users can open them in Case Designer from Process Center. About this task Case management functions are only available if you have IBM BPM Advanced with the Basic Case Management feature installed. If you configure a process application or toolkit so that users can open it in Case Designer, a link Open in Case Designer is displayed in Process Center. Procedure - To configure a new process application so that users can open it in Case Designer from Process Center: 1. Log in to Process Center. 2. Select the Process Apps tab. 3. Click Create New Process App. 4. In the Create New Process App window, enter a name and an acronym for your process application. 5. Select the Allow users to open the process application in the web-based Case Designer check box. - To configure an existing process application so that users can open it in Case Designer from Process Center: 1. Open the process application in Process Designer. 2. Click Manage. 3. Select the Allow users to open the process application in the web-based Case Designer check box. - To configure a new toolkit so that users can open it in Case Designer from Process Center: 1. Log in to Process Center. 2. Select the Toolkits tab. 3. Click Create New Toolkit. 4. In the Create New Toolkit window, enter a name and an acronym for your toolkit. 5. Select the Allow users to open the toolkit in the web-based Case Designer check box. - To configure an existing toolkit so that users can open it in Case Designer from Process Center: 1. Open the toolkit in Process Designer. 2. Click Manage. 3. Select the Allow users to open the toolkit in the web-based Case Designer check box. Parent topic: Building cases 423 424 Creating a case type A case type defines the activities that are needed to resolve a specific business problem. A case type also defines who works on these activities and the steps they take to resolve the problem. At run time, a business user works with a case, which is an instance of a case type. A case type also uses document types that define the documents that are required for the case. About this task Case management functions are only available if you have IBM BPM Advanced with the Basic Case Management feature installed. You create a case type from the Cases category in the library. Note:You can use only the Case Type editor to update a case type; that is, you cannot use an external tool. Procedure 1. Select Cases from the library. Click +. In the Cases menu, select Case Type . 2. In the New Case Type dialog, enter a name for the case type.For example, if you were creating a case type for the Credit Card Dispute Resolution application, you might enter Manage Dispute. 3. Click Finish. The Case Type editor opens for your case type in the Overview page. The case type that you created is added to the Case Type menu that is listed when you click Cases. 4. Optional: In the overview page, use the Documentation field to add information about the case type that you want to share with your development team. 5. Configure how the case is started in Process Portal. See Configuring how a case is started. 6. Assign teams whose members can start a case, or instance owner teams whose members can work with the case in Process Portal. See Assigning teams to a case type. 7. Create variables for the information that you want to share across activities. Create properties that are stored in case folders. Adding a case type variable or property. 8. Add activities that define the business tasks that make up the case. Add preconditions and behavior that determine how and when the activity starts. Implement the activity. Adding a case activity. 9. Creating user interfaces for the case Creating case user interfaces. 10. Adding folders that are used to group the documents in Process Portal and in the IBM BPM content store Adding case type folders. What to do next 425 - Configuring how a case is started A case can be started manually by an authorized user or automatically when a document of a specified type is added to the IBM® BPM content store. You can configure a case type to support both of these starting mechanisms. For example, a case might start when a customer submits an online complaint form or when a customer service representative initiates the case in response to a customer call. Adding a case type variable or property A variable contains information that can be shared among activities. A case folder property is a variable whose value is stored in the case folder and thus also visible to anyone directly interacting with the case folder. Adding case type folders Folders provide a way of grouping documents that are related to a case. You can create a folder structure that case workers in Process Portal can use to add documents that are required to complete the case. You create case folders in the case type editor. Assigning teams to a case type You can assign a team whose members can start a case, or an instance owners team whose members can work with the case at run time in Process Portal. Parent topic: Building cases Related concepts: Case management overview Designing a case application Related tasks: Creating a process application for your case types Creating a case type Creating a document type Related reference: Services to support case management applications 426 Configuring how a case is started A case can be started manually by an authorized user or automatically when a document of a specified type is added to the IBM® BPM content store. You can configure a case type to support both of these starting mechanisms. For example, a case might start when a customer submits an online complaint form or when a customer service representative initiates the case in response to a customer call. About this task Case management functions are only available if you have IBM BPM Advanced with the Basic Case Management feature installed. Procedure To configure how a case is started: 1. Open the case type that you want to configure. 2. Optional: Specify the type of document that can automatically start a case: A. In the Starting Document section of the Overview page, click Select to choose a document type or New to create a document type. B. Optional: To automatically initialize case folder property values with the values of matching document properties, select the Map document properties check box. If you select this check box, the properties on a starting document are matched to the properties on the case folder. Properties are matched based on the symbolic name, which is composed of the business object name, type, and cardinality. For example, assume that you have a business object that is called customerId of simple type string. Both the case type and the starting document type contain a property of type customerId. When a starting document is created, these properties are matched and the value of the case's customerId property is updated with the value of the starting document's customerId property.The identifier of the starting document is available as a JavaScript system variable: tw.system.currentProcessInstance.startingDocumentId. You can use this identifier in case activities, such as with Enterprise Content Management operations. The case type is started by the default snapshot of a process application. In Process Center, the tip is the default snapshot unless another snapshot was explicitly configured to be the default. If the case type is defined in a toolkit, it is started only if a snapshot of that toolkit is referenced by a process application. If multiple process applications reference the same toolkit that contains a case type with a starting document, multiple case instances are started. 3. Specify the team that can manually start a case by clicking Select or New for the Expose to Start option. You must select a team to work with the case in Process Portal. Parent topic: Creating a case type Related tasks: 427 Assigning teams to a case type 428 Adding a case type variable or property A variable contains information that can be shared among activities. A case folder property is a variable whose value is stored in the case folder and thus also visible to anyone directly interacting with the case folder. About this task Case management functions are only available if you have IBM BPM Advanced with the Basic Case Management feature installed. A variable can have a primitive type such as a String. A variable can also be a business object with either a complex or simple type. A case folder property can reference only a custom simple type business object. It cannot reference a complex type business object or one of the simple types, such as a String, directly. Procedure 1. To add a variable, select the Variables tab and click + beside Input, Output, or Private. 2. Beneath Details add an appropriate name and, if you want, a description in the Documentation field. By default, the variable has a String type. To change the type, click Select and select another type from the menu. To make a variable a list, that is, make the variable an array, select List. Select Visible in Process Portal to make a variable visible and available for searching in Process Portal. If you select Visible in Process Portal, a name in the Alias field is required. This name appears in the following places: - The Data section of the View Instance page - The Details section when you work on a task - The expanded task. 3. To use an existing business object as a type, click Select and retrieve the business object from the menu. To create a new business object, click New and follow the steps in Creating custom business objects in Process Designer. For example, in the Manage Dispute case type, you might require a business object to contain personal information about the owner of the credit card. You can add a CreditCardOwnerPersonal business object with these parameters. - cardNumber (Integer) - expiryDate (Date) - givenName (String) - surname (String) 4. Select + beside Case Folder Properties to create a variable that is a property of the case folder.In addition to the attributes for an input, output or private variable, case folder properties have display and symbolic names. The Display name field shows a generated name that is based on the property type. This name appears on the case folder in the IBM® BPM content store. If you create a case folder property that is called customerCardNumber and customerCardNumber is based on a simple type that is called CustCardNumber, then the Display name field becomes Cust Card Number. 429 In other words, the simple type name becomes the display name with a slight change for readability. The Symbolic name field shows a generated name that is based on the property type. You can use this name for Enterprise Content Management operations. A property that is a list must contain values when used. Null values result in an error. 5. The Visible Variables section shows the names and aliases of variables or properties that are identified as Visible in Process Portal. If you want, you can remove that visibility. 6. Save your work when finished creating your variables. Parent topic: Creating a case type Related information: Creating custom business objects in Process Designer Data mapping in Enterprise Content Management operations 430 Adding case type folders Folders provide a way of grouping documents that are related to a case. You can create a folder structure that case workers in Process Portal can use to add documents that are required to complete the case. You create case folders in the case type editor. About this task Case management functions are only available if you have IBM BPM Advanced with the Basic Case Management feature installed. Adding folders is a way to group logically related documents similar to paper folders in a desk. In a large, complex case, folders bring order to the many documents that accumulate over the resolution of the business problem. A folder can contain one or more subfolders. A case itself has a folder. The folders that you define for the case type are the initial set of folders that are automatically created when a case is started. At run time, you can add or remove subfolders under a specific case folder. In addition to Process Portal, case folders can also be accessed in the IBM BPM content store. Procedure 1. To add a folder, open the case type. 2. Click the Folders tab. You can create a folder directly under the root case folder, or under a previously created folder. 3. Click + beside the folder under which you want to create your folder. Add a name for your folder and save your work. You can create as many folders and subfolders as you want. For example, in the Manage Dispute case type, you might want to have several folders for the parties involved. You might create folders for information on the credit card owner, the vendor, and third-party corporations that are involved with the transaction. You might create this folder structure. - Credit Card Dispute Documents - Credit Card Owner Documents - Historical Documents on Owner - Monthly Transactions - Vendor Documents - Historical Documents on Vendor - Monthly Transactions - Third-party Services Documents - Delivery Records - Shipping Records What to do next The case folder and its subfolders are accessible through the Document Explorer coach view in the Instance Details UI that is provided with the Dashboards toolkit. See Default Instance Details template. If you are working with the IBM BPM content store on an Enterprise Content 431 Manager server, you can modify your Launch UI so that a user can view documents in the case folder that you specified in the Folders page. See Creating case user interfaces. You can also access the folder structure programmatically by using Enterprise Content Management operations. The identifier of the root case folder is available within a case as tw.system.currentProcessInstance.caseFolderId. When you create a subfolder programmatically by using the Enterprise Content Management operation Create Folder, you must use IBM_BPM_CaseSubFolder as the Object type ID. Parent topic: Creating a case type 432 Assigning teams to a case type You can assign a team whose members can start a case, or an instance owners team whose members can work with the case at run time in Process Portal. About this task Case management functions are only available if you have IBM BPM Advanced with the Basic Case Management feature installed. You develop your case type in the Case Type editor. At run time, you can start an instance of the case type, and case workers can view and start the case activities in the activity list in Process Portal. The Expose to start option determines the users who can start the instance in the Launch area in Process Portal. The instance owner team identifies the users who can work with the case. For example, for the Manage Dispute case type you might create a case owner team called Customer Service Representatives. Procedure 1. Open the case type for which you want to assign teams. 2. Click the Overview page. To assign the team of users that can start a case instance in Process Portal. 1. Select a team for the Expose to start option. You can also create a new team here. See Creating a team. To assign the team of users that can work on the case in Process Portal. 1. Select a team for the Instance owners option. You can also create a new team here. See Creating a team. 2. Save your work. Parent topic: Creating a case type Related tasks: Configuring how a case is started 433 Opening a dispute claim .Tracking the status of a case . you might have the following activities: .Initiating a case . For example. Typically a case has a number of activities. Procedure 1.Reviewing a document . Option Description 434 . 2. Open the case type for which you want to add an activity and switch to the Activities page. instead of having a single activity for the credit card dispute. About this task Case management functions are only available if you have IBM BPM Advanced with the Basic Case Management feature installed.Generating correspondence related to the dispute . Decide whether the activity is required or optional and create the activity in the appropriate section. and also define the order in which activities are performed by setting preconditions. you can also break a large activity into smaller.Adding a case activity An activity in a case is a discrete task that can be completed by a person or a system as part of that case. and add implementation logic.Opening a fraud investigation . To simplify a workflow.Requesting a document The case is not complete until all the required activities are completed and all running activities are completed. You add an activity in a case type and classify it as either is required or optional. more manageable activities.Requesting a copy of the sales receipt .Receiving a form from a customer . 435 . An optional activity can be started automatically. You can define preconditions that must be met to put a manual activity into Ready state. in the Behavior section of the General page. For example. However. Optional An optional activity is created as needed. your solution for automobile claims has a case type for automobile accidents. or manually as soon as the case is created or after preconditions are met for the activity. 1. Enter a name for the activity and optionally add a description in the Documentation field. You can create an optional activity that can be manually started for the rental car task. your solution for credit card disputes has a case type for claims with supporting documentation. The activity must be started by a user. the activity does not start until the case worker decides to manually start the activity. Next. A required activity can be started automatically or manually as soon as the case is created or after preconditions are met for the activity.Required A required activity must be completed before the case can complete. You can create a required activity for a claim review as soon as supporting documentation for a claim is added to the content store. Define how the activity is started: Option Automatically Manually Description The activity starts automatically when a case is created or when the preconditions are met for the activity. 3. define the behavior of the activity. For example. If you do not set any preconditions. Activities can start automatically after all the preconditions are met or manually by a user after all the preconditions are met. For more information. If you do not set any preconditions. See Setting preconditions. Parent topic: Building cases Related tasks: Implementing an activity 436 . the activity moves into the appropriate section. You can hide activities from users in Process Portal. A manual hidden activity can be started only programmatically. An activity that is marked as repeatable can occur multiple times during the lifetime of the case it is part of and can cause new activities to be created and repeated. Activities can start automatically after all the preconditions are met or manually by a user after all the preconditions are met. automatic activities start as soon as the case is launched and manual activities must be started by a user. Typically. If the activity is a background activity that users should not see. The activity does not appear in the Activities section in the Process Portal. by using the ActivityInstance. Define the implementation for the activity and map the data if it is required. Activities can be repeated as needed. You can mark an activity to repeat when there is a property change or when a document-filing precondition is defined for the activity. Define when the activity is ready to start by setting preconditions. Hidden activities can be started automatically or manually as soon as the case is created or after the preconditions are met for the activity. If the activity can be invoked multiple times. hidden activities are automatic but they can also be manual. If you change the setting here. even if the activity already completed. automatic activities start as soon as the case is launched and manual activities must be started by a user. see JavaScript API for IBM Process Designer and REST API for the Activity Instance (Ad Hoc) Resource.start() method. 4. select Hidden. but assigned users can view and work with resulting tasks in the Process Portal task lists. a subprocess. The behavior section provides another way to set an activity as required or optional. - Setting preconditions for case activities You can specify preconditions that must be met before the activity is ready to start. 1. or a client-side human service. 3. Implementing a case activity Case activities can be implemented with a linked process.2. select Repeatable. Setting preconditions for case activities You can specify preconditions that must be met before the activity is ready to start. 4. For example. .If both are defined. automatic activities start as soon as the case is launched and manual activities must be started by a user. If the expression evaluates to true. the activity starts.If there is a precondition event but no precondition expression. the precondition also determines when an activity that is already started changes state. a precondition event. Activities can start automatically after all the preconditions are met or manually by a user after all the preconditions are met. and select the activity that you want. Open the case type. In the Precondition Event section. the activity starts when the precondition event is met. then when the precondition event occurs. 2. If you do not set any preconditions. Switch to the Preconditions page. See Runtime states for activities in process applications. switch to Activities. Manual activities must be started by a user. In the case type editor. select the event that triggers the precondition expression to be evaluated. A precondition consists of two parts. from a waiting state to a working state. Precondition event No precondition event for this activity Description Automatic activities start as soon as the case is launched. 437 . About this task Case management functions are only available if you have IBM BPM Advanced with the Basic Case Management feature installed. and a precondition expression. the precondition expression is evaluated. Procedure To set a precondition: 1. 3. Note: In addition to determining when the activity first starts. The two parts together determine when the activity starts: . C. you can use JavaScript to access the identifier of the document that caused the activity to start: tw. A case property or variable is You can select multiple case updated properties or variables from the list provided.Inside the implementation of the activity. you might specify claimAmount is greater than 100. you might specify creditCardNumber is not equal to 0 and vendorName is not like Unknown. A precondition expression is There is no precondition event met to be triggered. Select Match All if both expressions must evaluate to true for the activity to start.enablin gDocumentID You can use this identifier to further process the document within the activity by using Enterprise Content Management operations. You can specify multiple expressions for the precondition.A document is filed in the case The activity starts when a document is added to the case.system. Specify the parameters of the expression. Any document typeThe activity starts when a document is added to the case. You must specify a precondition expression.currentAdHocActivityInstance. for the activity to start. A. Select Match Any if the activity can start when any one expression evaluates to true. For example. and when the expression is met. For example. including documents that are not contained in this process application. The activity starts when any of the specified properties or variables are updated.Choose one or more document typesThe activity starts when a document of any of the specified document types is added to the case. B. The expression must evaluate to true at the time the precondition event occurs. the activity starts. 5. This option applies to all documents. Parent topic: Adding a case activity 438 . Create an expression if your precondition requires it. Click the + icon in the Precondition Expression section heading. 439 . Under Priority Settings. When you create a new clientside human service.A task that is performed by a user in Process Portal. and the timezone that is used by the due in field. The user task is implemented as a client-side human service. All input and output variables are selected by default. specify your settings. In the Process Designer web editor.Linked process . Create your subprocess as described in Modeling non-reusable subprocesses. You can use JavaScript to specify these fields. or a client-side human service. . . A priority that ranges from lowest to highest establishes the priority you want for this activity in the Process Portal. 3. Specify a due in time.Calls another process within the process application. and then select the implementation. Add the details of the implementation that you selected: . . You can choose from one of the following implementations. the activity name is used. create your client-side human service as described in Building a client-side human service. About this task Case management functions are only available if you have IBM BPM Advanced with the Basic Case Management feature installed. a subprocess. In the Narrative field.Subprocess . you can enter a description or instructions for this activity. which creates the user interface.User task . 2.Client-Side Human ServiceYou can select an existing client-side human service. that is. . or create a new one.Warning: If you define a repeatable activity 440 .SubprocessDouble-click the activity and the subprocess editor opens. Open the case type. and select the activity that you want to implement. when the activity must be completed from the time the activity begins. Switch to the Implementation tab and select the activity type. Under Task Header.Implementing a case activity Case activities can be implemented with a linked process. You can clear the input and output variables that you do not want to use with your human service. specify a display name for the activity in the Subject field.A non-reusable process. Procedure 1. If you do not specify a display name. the input and output variables are automatically taken from the case type variables. multiple instances of the subprocess might be active at the same time (for example. . For input mapping. Parent topic: Adding a case activity Related tasks: Adding a case activity Related information: Subprocess types Client-side human services Building a client-side human service Creating a team 441 . To create a linked process. click the select a variable icon ( ). B. Working with linked processesNote: You cannot create a linked process from the case type editor. start the Process Designer desktop editor. Subprocesses have direct access to the case variables and therefore do not need data mapping. you must map the case variables to the client-side human service or linked process variables. Save your work. In some client-side human services. Then. Data mapping maps the case type input and output variables to the input and output variables of the client-side human service or linked process. repeat this procedure for the output variables. These instances concurrently access the same case variables and can therefore interfere with each other. Click the Data Mapping tab. 5. the mapping is complete since the wizard to create a human service creates the mapping as one of its steps.Linked ProcessSelect an existing linked process as the implementation. Select the input case type variable to map to the input variable from the linked process or human process. 4. when multiple documents arrive within a short time period). For client-side human services and linked processes. To create a data map: A.that is implemented as a subprocess. The properties provide the structure for your document type. In the New Document Type dialog. You can also set a precondition on an activity to start the activity when a document of a specified document type is filed in the IBM BPM content store About this task Case management functions are only available if you have IBM BPM Advanced with the Basic Case Management feature installed. This name appears in Process Portal and on the case folder in the IBM BPM content store.List: the property is a list (or array). you might enter SupportingCustomerDocumentation. 4. The Symbolic name field shows a generated name that is based on the property type. Enter the properties for the document type. In the Cases menu. Click Finish. These properties become fields at run time when a business user enters information in them. but it is visible in the IBM BPM content store. 442 . there might be a property for a system where the document is stored with a hidden attribute. and the user cannot proceed without entering a value for it. directly. If all vendors were available in a list. The symbolic name is a unique identifier for the property within the IBM BPM content store. Document properties also have display and symbolic names. SupportingCustomerDocumentation might have a property for the customer's credit card number with a required attribute. Also. such as a String.Creating a document type Document types classify the documents that belong to a case. 2. another property might be the name of the vendor that sold the goods to the customer with a list attribute. 3. The property is marked as required in Process Portal. Finally. . You create a document type from the Cases category in the library. The Document Type editor opens for your document type.Required: the property must be completed by the business user. Procedure 1. Document types provide order to the many kinds of documents that can occur in a case. enter a name for the document type. if you were creating a document type for the Credit Card Dispute Resolution application. . Click +. It cannot reference a complex type business object or one of the simple types. Select Cases from the library. 5. select Document Type. You can configure a case to start when a document of a specified document type is filed into the IBM® BPM content store. You can use the following attributes: . it cannot reference a custom simple type business object that has a base type of Selection.Hidden: the business user cannot see the property in Process Portal. For example. The Display name field shows a generated name that is based on the property type. You can use this name for Content Management Interoperability Services (CMIS).For example. Restriction: A document property can reference only a custom simple type business object. What to do next To rename or delete a document type. Parent topic: Building cases Related concepts: Case management overview Designing a case application Related tasks: Creating a process application for your case types Creating a case type Creating a document type Related reference: Services to support case management applications Related information: cleanupDocumentStoreProperties command 443 . you might update the properties of your document type. As time progresses. If you remove properties from your document type. select it in the Document Type list and either right-click or click the arrow to its right. the removed properties still appear in Process Portal. The removed properties remain active until they are deleted from the embedded content store by using the cleanupDocumentStoreProperties command. You can provide more information about the documents by assigning properties to the document type. - Example document types Document types help you to organize and classify the documents that belong to a case. such as letters sent to Claim number. effective date of the automobile policy and formal changes to policy. such as an Claim number. vehicle identification Proof of ownership. policy the policy number. date of loss. automobile registration from a state customer surname. customer given name. vehicle evaluator or photographs of the identification. You define document types to group similar documents and the information about the documents that are related to the case. customer surname. customer given name. vehicle licensing agency or a bill of sale identification. estimate for a new windshield from a customer surname. vehicle identification Repair estimation documents. such as the Claim number. policy type.Example document types Document types help you to organize and classify the documents that belong to a case. date of application. such Claim number. repair glass repair company item. Table 1. For example. customer given name. such as the written Deductible amount. estimate total. customer given written application form name. the customer about the claim customer surname. You can provide more information about the documents by assigning properties to the document type. Case management functions are only available if you have IBM BPM Advanced with the Basic Case Management feature installed. policy number. Examples of automobile claim document types and properties Document type and description Properties that are related to this document type Policy documents. vehicle identification Claim forms. You can create as many document types and properties as needed. date of loss. such as the initial Customer address. as the report from insurance claim customer surname. policy type. policy broken windshield number. customer phone number. type of loss. date of loss. date of loss. vehicle license plate number Parent topic: Creating a document type 444 . vehicle identification Application forms. customer given name. vendor name Damage assessment documents. vehicle replacement value damaged windshield Correspondence. such as a claim for a Claim number. expiration date of policy. an automobile claim case might have these document types and properties. You can create these user interfaces: . which includes a generated coach. the user interface that is provided by IBM BPM is used. Switch to the Variables page. The client-side human services editor opens. IBM® Business Process Manager provides a user interface for your instances in Process Portal. you see a list of case variables that you can add to your human service. In the New Client-side Human Service page. You can create a client-side human service and specify it as the user interface for the instance owners. you can also create your own user interface that is customized for instance owners. if you click Next. You can edit these variables only in the case type editor. 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. 4. Select the interface that you want to create. first create a client-side human service. 1. for example Default under Details UI. Click New beside Client-side human service and enter a name for your user interface. 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.The Default user interface that overrides the user interface that is provided by IBM BPM. Notice that the input and output variables that are mapped from the case type are locked.The Launch UIDefault user interface is seen by members of the team that is assigned to the Expose to start option in the Overview page. . Switch to the Views page. You can then create your customized interface by modifying the generated service and coach. Procedure To create a case instance user interface. 5.Creating case user interfaces Create user interfaces that a user sees for the case instance in Process Portal.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 cannot implement it as a heritage human service. 2. If you do not specify a client-side human service here. Optionally.You do not need to map the variables between the case type and the human service. Open the case type for which you want to create the user interface. Attention: A process instance user interface must be implemented as a client-side human service. 445 . The case type variables are already mapped to the human service variables with the same name. Select the variables to be added to the interface of the human service. . 3. About this task Case management functions are only available if you have IBM BPM Advanced with the Basic Case Management feature installed. Displays the values of the variables that are passed into the human service. use coach controls that are provided in the Content Management toolkit for viewing and retrieving documents in the content store. Test the client-side human service. . they are removed.Document Explorer control Note: If the case launch is canceled. which returns an error if the instance is not found. If the value of cancelCase value is false. 8. If the value of cancelCase is true when a user completes the launch case human service. the cancelCase variable is set to true. A basic diagram is generated for you. Documents that are also used outside the case folder remain in the content store. the generated human service has an Enter Data coach. . OK and Cancel. The value of the variable is set by the launch UI human service.Data section . The default value is false. The default value is false. the launch is canceled. If you are working with the IBM BPM content store on an Enterprise Content Manager server. with a control for each mapped case type variable and property. the case folder is removed from the IBM BPM content store.You can. Otherwise. called Instance Details UI Services Template. For more information. Double-click the coach to open the Coaches page. the launch is canceled. These controls are available in the Content Management toolkit. Process Designer generates a cancelCase variable of type Boolean.For a Launch UI. click Run to test the client-side human coach. the generated human service has two coaches: . you cannot change or delete it.Show error. 7. see Instance Details UI Service template .How to use coach views to store or view documents . Complete the human service diagram and customize the coaches.Displays the instance details in Process Portal . For example. To do so.Default Instance Details Template . 446 service and the . The human service is generated from a template in the Dashboards toolkit. . For more information. the case is started. 9. you can modify your Launch UI so that a user can view or add documents in the case folder that you specified in the Folders page.For a Details UI. see: . The generated Launch UI has one coach with two buttons. If a user clicks Cancel. The value of the variable is set by the launch UI human service. If the value of cancelCase is true when a user completes the human service during case launch. If the value is false. Switch to the Diagram page. however. When you specify a launch case UI. add private variables that are available only to the human service. Process Designer generates a cancelCase variable of type Boolean. You can only view this variable. which contains the following coach controls: . the case is started.View Instance Details coach.For Launch UI. If you are creating a launch case UI. 6. the Document Explorer control. Add a script task to insert some temporary test data. During synchronization. Remove the logic in the human service that shows an error if the process instance id is null. C.For Details UI. B. Regenerating replaces any customization that was done in the human service. Run the human service D. Parent topic: Building cases Related information: Client-side human services 447 . you can optionally choose to regenerate the human service body. What to do next If your variables change in the future. you can use the Sync button to synchronize the variables and human service.. . After you are satisfied that the service works as expected.If you want to incrementally test and build your custom UI: A. run the instance UI within Process Portal. remove the temporary script and then test again by running the instance UI within Process Portal.If the human service flow is not customized. do one of the following: . you must play back the case type in the Process Designer desktop editor. You can run and debug the implementations of your activities. 2. Click and activity to select it and click Run or Debug to launch the Inspector. Case management functions are only available if you have IBM BPM Advanced with the Basic Case Management feature installed. 3. you must play back the case type in the Process Designer desktop editor. The Inspector opens showing the case type as a BPD. human services. 5. See Running and debugging client-side human services. Open the case type and drill into the activity to open the client-side human service. 5. To view the user task activities (client-side human services) in Process Portal. In the library. Subprocess activities To test and debug an activity that implements a subprocess.Testing and debugging a case type Play back your case type in the Inspector to test and debug your activities. 2. Depending on whether you are testing or solving a problem. Parent topic: Building cases 448 . you start the Inspector from the Process Designer web editor or the Process Designer desktop editor. click Cases and select the case type that you want to test. In the library. At the Switch View prompt. 2. click Run or Debug. 3. 1. Case type To test and debug a case type. 1. Open the process application that contains the case type in the Process Designer desktop editor. 7. subprocesses and linked processes. Click the subprocess activity and click Run or Debug to launch the Inspector. Right-click the case type and click Playback > Run Process 4. You can test and debug your case type in the Inspector to test your activities. click Cases and select the case type that you want to test. At the Switch View prompt. 6. The Inspector opens showing the case type as a BPD. Click Executing Phase to view the activities. Open the process application that contains the case type in the Process Designer desktop editor. click Run the details UI for the selected BPD instance. click Yes. Right-click the case type and click Playback > Run Process 4. Click Executing Phase to view the activities. 6. User task activities You can test and debug a user task activity by running the client-side human service that implements the activity. Depending on the type of activity. click Yes. 1. 449 . 450 . Click Implementation in the Properties view. Enter a name for the service on the following dialog box and click Finish. The mapping structure for each operation is shown in Data mapping in Enterprise Content Management operations. as you need access to the Enterprise Content Management (ECM) types.Select User Interface and then +. 1. IBM BPM content store supports all Content Management Interoperability Services (CMIS) operations. From the menu.Select Implementation in the library section and then +. Click the auto-map icon to create these private variables ( ). Select IBM BPM content store to create a case service.Select User Interface and then +. You can create them manually by yourself or use the auto-map function. From the menu. The editor opens with the Diagram view in focus. the Server name input map is enabled and editable. The auto-map function creates private variables for the business objects. 2. select Human Service. select the Content Management toolkit version that you require. . . select Integration Service . 5. select + beside TOOLKITS. Add the Content Management (SYSCM) toolkit to your dependencies if it is not there. 4. The following services contain a Content Integration step. These services. In the Add dependency menu. Under Enterprise Content Management Server. <Use data mapping> is the default selection in the Server field. can be shared by all case types in a process application. Select any service from the library area that supports Content Integration steps. To add this toolkit dependency. Case management functions are only available if you have IBM BPM Advanced with the Basic Case Management feature installed. It means that in the Data Mapping tab section. Create the map between the variables for input and output. 6. select Ajax Service. which are used by the service you create. Save your work to update the process application with any changes to your service.Services to support case management applications You can create services to use with your case management applications. 3. From the palette. Click Data Mapping. From the menu. Under Content Operation. select an appropriate ECM operation. These variables must be created. drag a Content Integration step to the canvas and provide a meaningful name for it. which can do standard tasks in your case management applications. The server type is IBM® BPM content store. A service to support a case management application uses its own server type. system.currentProcessInstance. Parent topic: Building cases Related concepts: Case management overview Designing a case application Related tasks: Creating a process application for your case types 451 . the identifier is null.currentAdHocActivityInst ance.enablingDocumentID JavaScript API.system. which contains the identifier of the root case folder. Requires the tw. You must specify this type in the Object type ID parameter of the Create Folder operation. If the case was started manually. The identifier is null for activities not started by a precondition of a document filed in the case. Requires the tw. Table 1. Referencing content of a case by using JavaScript Content or function referenced Accessing the case folder JavaScript required in the Enterprise Content Management operation Requires the tw. which contains the identifier of the document that started or enabled the case activity.s tartingDocumentId JavaScript API.Enterprise Content Management operations can reference the content of a case by using JavaScript.currentProcessInstance. which contains the identifier of the document that initiated the start of the case. Creating a subfolder under a case folder Every subfolder of the case folder must be of type IBM_BPM_CaseSubFolder.c aseFolderId Accessing the starting document of a case Accessing the enabling document of a case activity JavaScript API.system. Creating a case type Creating a document type Related information: Outbound interactions with Enterprise Content Management systems Inbound events from Enterprise Content Management systems 452 . Case management functions are only available if you have IBM BPM Advanced with the Basic Case Management feature installed. It supplants the document attachment feature that was used in earlier releases.The IBM BPM content store The IBM® BPM content store is a CMIS-enabled embedded document repository that is used to store IBM BPM documents in IBM Business Process Manager Advanced version 8.0 or later.5.5. The IBM BPM content store supports all Content Management Interoperability Services (CMIS) operations and most inbound events and you can use either Coaches or Heritage Coaches to work with IBM BPM documents in the content store. Parent topic: Building cases 453 . . . For example. Instead. At run time. Case artifacts are created or updated in the IBM BPM content store in the following ways: . It can also happen if you had a property on a tip and then deleted the property without taking a snapshot. For document types. Unlike the IBM Business Process Manager repository. Changes to the properties on the case folder instance are automatically synchronized back to the case instance. there is one document class definition in the IBM BPM content store that has all properties that are defined on all snapshots and the tip. You continue to develop your 454 . there is also a case folder definition in the IBM BPM content store. For each case type. a case starts or a document is created in Process Portal. that is. all case folder properties that are defined in all snapshots and the tip are available in one case folder definition. .When the document type is used in either a Content Integration step or event subscription that target the IBM BPM content store.store Case artifacts and the IBM BPM content The IBM® BPM content store contains the generated case folder and document definitions and the case artifacts. a case not only consists of the activities that are run like a business process definition. . Cleaning up properties and removing case folder instances For both case types and document types. The selection of the document type in the Process Center causes the update. It is kept in synchronization with the case folder properties defined in the case type. The case folder is a separate artifact that is created in the IBM BPM content store for each case instance.When a snapshot is installed on the Process Server. a business process definition or a case starts from the tip or a named snapshot. potentially causing a precondition change. the IBM BPM content store does not save different versions of a case folder definition.When a playback occurs. changes to variables that are made in activities that use case folder properties are automatically synchronized to the case folder instance. Behavior of the IBM BPM content store In IBM Business Process Manager. However. you have a snapshot that contains two case type properties. a property might still be available in the deployed definition in the IBM BPM content store although it is not available in any snapshot or tip. This situation can happen if you deleted snapshots.When a TWX file is imported into the Process Center. Case management functions are only available if you have IBM BPM Advanced with the Basic Case Management feature installed. This takes place in the Process Center.When a snapshot is taken in the Process Center. but a case also has a case folder. for example. You remove one of the properties but do not take a snapshot. The property that you removed is still available in the corresponding IBM BPM content store artifact definition. use the cleanupDocumentStoreProperties command. by using the IBM Administration Console for Content Platform Engine. all case folders and documents that belong to that process application are removed. - Update restrictions for modifying case artifacts You can update case artifacts and then playback or redeploy a process application. To clean up these properties. The redeployed process application contains case types and document types previously deployed. and contained documents are kept for archival purposes. you can update a process application and then playback or redeploy the process application again. With the removal of the process application. For example. The only exception to this rule is the removal of a process application in the Process Center. The case folder. See the related links at the end of the topic. You need to explicitly remove them. it is not cleaned up when the instance is finished and deleted. its properties. Parent topic: Building cases Related reference: Redeployment restrictions for modifying a process application Related information: Cleaning up the IBM BPM document store cleanupDocumentStoreProperties command Limitations in administering the IBM BPM document store 455 . While a case folder is automatically created when a case instance is started. Modifying a case type or a document type and then redeploying the process application affects existing case and document data and new case and document data.application that is now on the tip. Affects of process application changes Type of changes Result New item.artifacts Update restrictions for modifying case You can update case artifacts and then playback or redeploy a process application. the old property will continue to be available. such as a No issues. Delete a property definition from a document or case type. When working with a document or case folder using the Enterprise Content Management integration tools. The result of changes in the IBM® BPM content store is discussed. 456 . Add a property definition to a document type or case type. No issues. The following table describes the effects of updating case artifacts and then playing back or redeploying a modified process application. changes column for the Required property setting for document type properties. Delete an item. Case management functions are only available if you have IBM BPM Advanced with the Basic Case Management feature installed. The redeployed process application contains case types and document types previously deployed. as a document type or a case type. Table 1. such No issues. The property is not removed from the corresponding class in the IBM BPM content store. Comments The item is not removed from the IBM BPM content store. you can update a process application and then playback or redeploy the process application again. Existing items can be See the Type of affected. Modifying a case type or a document type and then redeploying the process application affects existing case and document data and new case and document data. These changes are relevant only when you are working with the IBM BPM content store through the Enterprise Content Management integration tools. For example. new document type or a new case type. the old property will continue to be available. No issues. a business object that is associated with a case type or document type property. The cardinality change results in the addition of a new (multi or single value) property to the corresponding class in the IBM BPM content store.Change the name of No issues. in a case type or document type. All existing and new instances of a case and document class in the IBM BPM content store use the updated property description. Change the cardinality of a document type or case type property definition. the old property will continue to be available. When working with a document or case folder using the Enterprise Content Management integration tools. When working with a document or case folder using the Enterprise Content Management integration tools. . The old property corresponding to the original version is not removed from the class definition. The old property corresponding to the original version is not removed from the class definition. 457 The business object change results in the addition of a new property to the corresponding class in the IBM BPM content store. Change the property Existing items are definition description affected. Case folder classes are unaffected by the validation settings change with one exception. Changing the validation setting values can cause a document to have invalid values. . the validation setting values are enforced by the Business Process Manager engine at run time. 458 In the case of documents. This method changes the metadata of the underlying property template. the existing values are validated against the new setting of the validation value only when there is an update to the property. None of the other validation setting values are set in the corresponding case folder class property. this change affects all document classes that use the same business object in a property definition. New instances are validated against the new validation setting value. The value is set to the greater of the existing and new values. However. As a result. Changing the maximum length of a string business object might reset the maximum length of the corresponding string property for all case type definitions that reference the same business object.The validation settings for a simple type business object that is used in a case type or document type property Some existing items are affected. If the property business object used was changed from in a case type or hidden to visible. then all existing instances and new instances do not display the property. If the property was changed from visible to hidden. Results column for new instances use the validation settings the updated for a simple type setting. case use the updated folder structure. See the type properties. New instances require a value for the property. the property must be set with a valid value. then document type all existing property. Document type name New and existing New and existing and description. Case folder structure New cases are New instances of the for a case type. affected. Before you can check out an existing document that contains a required property. items are affected. Hidden property Existing items are All existing instances setting for document affected. Existing instances require a value for the property only if the instance is updated. instances of the document class in the IBM BPM content store use the new display name and description. Results column for the validation settings for a simple type business object used in a case type or document type property. Parent topic: Case artifacts and the IBM BPM content store Related information: 459 . instances and new instances display the property. See the of the property and type properties.Required property Some existing items setting for document are affected. cleanupDocumentStoreProperties command 460 . Assign a team to an activity or a lane in a business process. Select the team of managers that can manage the team's tasks in the Team Performance dashboard. 5.Specify a team of instance owners for a case type. Open the team. 4. Because any team can be added as the manager of another team. Teams are used to manage the tasks that users can perform in Process Portal. . You can use teams in a number of ways in Process Designer: .Creating a team A team is a group of users that perform similar tasks. . 6. or you can use a team retrieval service to define a team dynamically at run time. so that users in that team can work with case instances of that type in Process Portal. Procedure To create a team and add members. B. and consists of a set of members and a team of managers. These settings represent the performance expectations for the team. follow these steps: 1. 2. Open the Process Designer desktop editor. you can flexibly define your organization's management structure. IBM® BPM ignores the tw_allusers user group for task reassignment. . see Setting simulation properties for teams A. set the simulation properties for the teams that are assigned to the swimlanes in the process model. and run simulation on the business process activity. See Setting up a team retrieval service. In the New Team window. If you want to simulate a process. and enter the simulation properties. add individual users or other groups instead of using tw_allusers. To add the members to a team.Provide a team with the authority to view performance data and the performance dashboard in Process Portal. .Note: To select a service to dynamically retrieve a team at run time.Select users or groups that are defined in the user registry. For task reassignments. For more information. click the plus sign to next to the Teams category. you can directly add users or groups from the user registry. you must start the Process Designer desktop editor. which is shown when you click Teams. Select the team members in one of the following ways: . or you can select a service that you have already created. Your team is added to the list of teams. In the library. . Click Save in the main toolbar.Using services to define dynamic teams You can use the team retrieval service and the team filter service to dynamically 461 . enter a name for the team and click Finish. Tip: To prevent problems occurring when there is a large number of users in the system. You can create a new service.Set simulation properties for a team to define the performance expectations for the team.Use a service to dynamically retrieve a team at run time. 3. The users in that team can work with the tasks that are created for the activities in Process Portal. Defining Team rules (deprecated) When you choose to establish team members by using an expression.Setting up a team filter service You can use a team filter service to dynamically prevent certain users from being assigned to an activity. you can define the management structure of your organization. .Setting up a team retrieval service You can define a service that dynamically returns a set of users and managers at run time. with teams managed by teams.determine who is eligible to perform activities. Parent topic:Building process applications Related information: Setting up a team retrieval service 462 . In this way. . you must select a team of managers.Defining team managers To define who the managers of a team are. you can define rules to determine those members. These services can take parameters from environment variables to influence the team selection. . . The filtering can be based on any criteria and can use input parameters from relevant process variables to determine which users to filter out. to implement a separation of duties policy. You can create team filter services to implement assignment policies. you must be in the IBM® Process Designer desktop editor. If you want the team to be used as the managers of another team. When you assign an activity to a team that is defined by a team retrieval service that uses extra parameters. you might need to remove the user who performed the previous activity from the list of users who can perform the next activity. or remove members who are not available. and managerTeam for the name of the team of managers.Using services to define dynamic teams You can use the team retrieval service and the team filter service to dynamically determine who is eligible to perform activities. a list of members (users or groups) and. Team filter service There are times when you do not want the whole team to be assigned to a task. These services can take parameters from environment variables to influence the team selection. The structure of teams Each team has a name. with fixed members and fixed managers. The team filter service takes the initially resolved team as a parameter and must return the filtered team as a Team object. In that case. Teams can be associated directly with activities. To improve performance. Prerequisite: To create or edit a team that uses a retrieval or filter service. Instead of using a statically defined team. Team retrieval service Instead of defining static teams. Only the managers can perform managerial actions. The service receives the name of the team as a string parameter. you can only use additional input parameters that have default values that are defined for them. Because any team can be assigned as the managers of another team. the name of a team of managers. you can implement a separation of duties policy. If necessary you can add extra input parameters that are required to filter the team. the filter service needs an input parameter for the user 463 . name for the name of the team (which is ignored). these services can use service result caching. For example. optionally. it is possible to define teams to reflect the managerial structure of your organization. For example. and returns the resolved team as a Team object. You can use a team filter service to eliminate particular members from performing the associated activity. you must define which environment variables or literal values are mapped onto each extra input parameter. If necessary you can add extra input parameters that are required to resolve the team. the service must return a Team object. but rather a subset of the team. you can create teams whose members and managers are dynamically resolved by a team retrieval service. but managers can also be members of the team that can perform an activity. When a team is resolved dynamically by a team retrieval service or filtered by a team filter service. you can use a team retrieval service that returns a list of team members and the name of a team of managers. or assigned as default teams to lanes. The returned Team object consists of a list of team members in the members field and the optional fields. results are refreshed after 12 hours. see the developerWorks article Teams in Business Process Manager V8. If you add more than the defined cache size. Parent topic:Creating a team Related information: Setting up a team retrieval service Setting up a team filter service 464 .5. inside the <server merge="mergeChildren"> section. the service results cache setting for the nested service is ignored and the results for the nested service are not cached. You can change the size of the cache by including a value for <service-result-cache-size> in the 100Custom. the cache stores up to 4096 results. Part 2: Developing services for dynamic team resolution. you can enable the service result cache for any team retrieval service or team filter service. Caching team service results If appropriate. Restriction: The service results cache setting works only for top-level services. By default. which are services that are directly started by a BPD. the results of top level services are cached for unique combinations of input parameter values to improve performance. When a service is called by another service. but this value can be changed.ID that is to be removed from the input team. If. for example. the least recently used result is removed so that there is space for the new result.xml file. By default. you might create a filter named High claim value team filter that uses an input parameter claimValue to filter out any users that are not qualified to work high value claims. When enabled. insurance claims above a certain threshold can be handled only by particular team members. For more examples. click the plus sign to next to the Teams category. By default caching is disabled. for example. the results for each combination of input parameter values are kept in the cache for 12 hours. A. In the team editor. If you want to create a team that is dynamically resolved. Select the Diagram tab and provide the implementation of the service. The mandatory input and output variables are already present and are locked. select the Overview tab. the Cache results for section is not displayed. when caching is enabled. select Enable caching of service results to display the cache configuration fields. About this task A team retrieval service can use custom defined input parameters to resolve a set of team members and team managers. complete the following actions in the Designer view. . E. A. To change the caching period. In the library. you might need to tune the size of the service results cache to avoid memory problems. Minutes. If the new team retrieval service requires information from the activity. add input parameters and specify the variable details. 3. 2. you must be in the IBM® Process Designer desktop editor. Before you begin To perform this task. It can also optionally include the name of a team of managers. C. enter a name for the team and click Finish. If you want the results of the service to be cached for each combination of input parameter values. You can change the size of the cache by setting a different value for <service-result- 465 . Important: If you want to use this dynamic team as the managers of another team. and optionally the name of the team (this parameter is ignored). By default. the cache stores up to 4096 results. Open the Process Designer desktop editor. In the New Team window. Important: Depending on the size of the results. Hours.When caching is disabled. and Seconds fields to select the duration that you want. the Cache results for section is displayed. Click New. Claims Team Retrieval Service. B.When caching is enabled.Setting up a team retrieval service You can define a service that dynamically returns a set of users and managers at run time. By default. you can use only additional input parameters that have default values that are defined for them. use the Days. then in the Service Result Cache section. Based on the input parameters. D. Enter a suitable name for the service. Procedure 1. B. choose to specify team members by using a service. the service must return a Team object that contains a list of team members. Select the Variables tab. . For each required parameter. B. Parent topic:Creating a team Related information: Creating a team Setting up a team filter service Using services to define dynamic teams 466 .cache-size> in the 100Custom.xml file. To use an existing team retrieval service. as described in Assigning teams to BPD activities.businessPriority. complete the following steps. 5. 4. for example tw. When a service is called by another service. If the team retrieval service that you selected requires extra parameters. Select the team retrieval service that you want to use. it is available to select when you assign activities to teams. If you defined a new team retrieval service. which are services that are directly started by a BPD. the service results cache setting for the nested service is ignored and the results for the nested service are not cached. A. Restriction: The service results cache setting works only for top-level services. Click Select. Results The team's members are determined dynamically by the appropriate team retrieval service. inside the <server merge="mergeChildren"> section. A selection dialog is displayed that lists all existing services that match the team retrieval service template.env. then the Team Retrieval Service Input Mapping section is displayed. enter the corresponding environment variable name or literal. and any default value. the service must return a Team object that contains a list of team members. Before you begin To perform this task. to implement a separation of duties policy. If you want the results of the service to be cached for each combination of input variables. Enter a suitable name for the service. Based on the input parameters. The results of the team filter service are then subject to the selected user distribution. specify the name of the variable. About this task The team filter service is optional. Click the plus sign in the All category. and create an Integration Service.Setting up a team filter service You can use a team filter service to dynamically prevent certain users from being assigned to an activity.local. If you choose to use it. If the new team filter service requires information from the activity. for example. select Enable caching of service results to display the cache configuration 467 . or to the dynamic team returned by a team retrieval service. It can also optionally include the name of a team of managers. Similarly. and optionally the name of the team (this parameter is ignored). 7. its type.user. 3. In the Details section. then in the Service Result Cache section. then you implement the service so that it eliminates ineligible users and returns a team object that contains the remaining users who can be assigned. the service might need the process variable tw. Tip: The input variables that are required depend on the policy that the filter must implement. Select the Variables tab. Using a team filter service allows the team to be narrowed down according to whatever criteria or policies you choose to implement. where the user who completed the previous activity cannot be assigned to the following one. Procedure 1. 5. click Add Input to specify more input parameters. for example.id so that the service implementation can remove the previous user from the input team.estimatedClaimAmount as an input parameter that the service implementation uses to determine which users to eliminate from the input team. you might specify an input variable previousUser that you map to the process variable tw. 2. Select the Diagram tab and provide the implementation of the service.system. certain users cannot work on tasks that are above a certain value. you first define the input variables that the service receives with the input team object. Select the Team Filter Service template and click Finish. The mandatory input and output variables are already present and are locked. 4. for example.filter out previous user. To define a team filter service. select the Overview tab. The filtering can be based on any criteria and can use input parameters from relevant process variables to determine which users to filter out. the filter is applied to the static team associated with an activity or case. Open the Process Designer desktop editor. High Value Claims Team Filter Service or Separation of duties . 6. If. you must be in the IBM® Process Designer desktop editor. Parent topic:Creating a team Related information: Setting up a team retrieval service Using services to define dynamic teams 468 . By default caching is disabled.xml file. when caching is enabled. You can change the size of the cache by setting a different value for <service-result-cache-size> in the 100Custom. For each required parameter. you might need to tune the size of the service results cache to avoid memory problems.Important: Depending on the size of the results. What to do next Apply the new team filter service to the team that is assigned to an activity by completing Assigning teams to BPD activities. By default.fields. the cache stores up to 4096 results. Results The new team filter service is added to the list of team filter services that you can select when you assign a team to an activity. the Cache results for section is not displayed. 8.When caching is enabled. then the Team Filter Service Input Mapping section is displayed.estimatedClaimAmount or 8000. . If the team filter service that you selected requires more parameters. the service results cache setting for the nested service is ignored and the results for the nested service are not cached. Minutes. Restriction: The service results cache setting works only for top-level services. . inside the <server merge="mergeChildren"> section. enter the corresponding process variable name or literal. which are services that are directly started by a BPD. the Cache results for section is displayed. Hours. To change the caching period. and Seconds fields to select the duration that you want. the results for each combination of input parameters are kept in the cache for 12 hours. use the Days.local.When caching is disabled. for example tw. By default. When a service is called by another service. and accessing the Team Performance dashboard in Process Portal. A. you can define the management structure of your organization. C. 2. Parent topic:Creating a team 469 . you must select a team of managers. or delete the currently selected team of managers. Before you begin If the managed team is dynamically resolved by a team retrieval service. complete the following actions. Even when a team has only one manager. changing the priority. complete the actions in Creating a team. Only members of the appropriate team of managers can access managerial functions. changing the due date. You can either create a team. Add or remove users and groups in the members list. with teams managed by teams. select an existing team. complete the following actions using Process Designer. If you want to define a new team of managers. If you want to add or remove managers from an existing team of managers. B. 1. For more information. reassigning a task.Defining team managers To define who the managers of a team are. see Setting up a team retrieval service. Procedure For statically defined teams. you must implement the team retrieval service to return the set of team members and the name of a team of managers. you must create or select a named team that contains that manager. use the Managers section. Open the team of managers that you want to modify. Optional: To modify the team that manages this team of managers. such as viewing a task's details. In this way. Click select participant to choose an existing team. Enables user selection that is based on user attributes. 2. Procedure To define rules. Table 3. Click Add Rule to choose the type of rule you want. . follow these steps. Table 2. you must open the Process Designer desktop editor. Who have an attribute select user attributeequal toenter value. 3. 4. Open the team that you want to edit.For a User Attribute Rule. Enables the selection of users who match a particular expression that you provide. You can configure IBM® Business Process Manager to deactivate these triggers. Supply the necessary information for the type of rule that you choose. you can define rules to determine those members. Input required for a Participant Rule Expression belong select participant Action Click belong to choose either belong or do not belong. 1. supply the input that you want for the following specification: Who belong to team select participant. See Deactivating dynamic group updates. supply the input that you want for the following specification.For a Participant Rule. This procedure triggers dynamic group creation. Open the Process Designer desktop editor.Defining Team rules (deprecated) When you choose to establish team members by using an expression.When you define team rules. Input required for a User Attribute Rule 470 . Before you begin To perform this task. which can be time consuming. Rule types available for defining teams Rule type Participant Rule User Attribute Rule Expression Rule Description Enables user selection according to team membership. you have the following types from which to choose: Table 1. . For example. or greater than or equal to. . Input required for an Expression Rule Expression match enter value Action Click match to choose either match or do not match. greater than. Be sure to surround any strings in the expression with double quotation marks. Click enter value to display a field in which you can enter either an IBM BPM variable or a JavaScript expression that produces the value that you want to compare. less than. supply the input that you want for the following specification: Who match expression enter value. you can enter an expression that returns a default value when the complex variable is null and the attribute for the variable otherwise.targetView. less than or equal to. Parent topic:Creating a team 471 . Be sure to surround any strings in the expression with double quotation marks. the expression can be:tw.processData==null ? "":tw. if the user attribute is a string. The expression must evaluate to a specific user name. Table 4.Expression select user attribute equal to enter value Action Click select user attribute to select an existing user attribute definition.For an Expression Rule.local.processData. Click enter value to display a field in which you can enter either an IBM Business Process Manager variable or a JavaScript expression that produces the value that you want to compare. Click equal to to choose from: equal to. when you select Using Expression and define a User Attribute Rule. For example.local.complexity Note: Users that do not have a value set for the selected user attribute definition are ignored for any of the operators. not equal to. 472 . you can provide this type of flexibility.Creating exposed process values (EPVs) In IBM Process Designer. . Each variable has its own type and scope. .Variable types in Process Designer You can use the variable types provided by the system toolkits. For example.Using JavaScript in BPDs You can use JavaScript in many business process definitions (BPDs) in Process Designer to improve the behavior of your model. you must initialize all complex variables and all lists (arrays) before you can use them in a BPD or service. if you create a process to handle expense reimbursement. . Understanding the generation rules and some suggestions for business object creation can be helpful when your business objects will be used with IBM Integration Designer. all variables declared for a business process definition (BPD) or service are local variables. For example. task assignments. 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.XSD generation pattern for business objects When you create a business object. you may want to enable supervisors to change the allowed amounts for daily expenditures.Variable scope in Process Designer In IBM BPM. . and so on. or the dollar amount that coincides with various levels of approvers.Business objects and variables In Process Designer. . you can write JavaScript to implement a step in your process and embed that script in an activity. These variables can be modified by the users while instances of a process are running. or you can create custom business objects. you can create custom variable types called business objects. By creating EPVs. thereby affecting the flow of all running process instances. depending on the requirements of the business data included in your process. an XML Schema Definition (XSD) is generated. .Making business data available in searches and views Before business users in IBM Process Portal can search for business data across 473 .Declaring and passing variables Variables capture the business data that is passed from step to step in a process. . you can create exposed process values (EPVs) to define a set of variables you want to expose to specific users. . . All variables you create must be declared before you can start using them. which is also referred to as a custom variable type. such as the System Data toolkit.Creating business objects When no system data toolkit variable types or business objects match your specifications.Setting variables in pre and post assignments You can set pre and post assignments for variables when you want to assign a value to a variable immediately before or after an activity or event runs.Initializing complex variables and lists In Process Designer. allowing users to adjust specific variable values as constants. . In addition. Parent topic:Building process applications 474 . you need to configure each variable in the Process Designer to be available to search.process instances. the business data about a task that business users see in their task list needs to made available to search in order to be viewable in the task list. A selection is a list of different values. Accepts digits with up to two decimal places. it is converted to and behaves like a date. of which the user can select only one. the system toolkits are imported into the Process Center repository so that each process application and toolkit that you create has access to a common system data. The following table provides more information about the base business objects (variable types) provided in system toolkits. A list of all the system types is provided in the JavaScript API reference guide.Base types allow you to create custom variable types called business object. Allows date formats to be entered into the variable as times.System types are provided variable types that cannot be modified. such as the System Data toolkit. Provided base types Base types String Integer Decimal Date Time Selection Boolean Description Allows alpha-numeric characters to be entered into the variable.System types . such as 45. depending on the requirements of the business data included in your process. such as 45 or 20.3 or 20. Accepts digits without a decimal place.Table 1. Allows you to provide a list of possible entries to a user. It appears at run time on a Coach form as a check box. A selection variable appears at run time on a Coach form as a dropdown list or as radio buttons. The system toolkits provide the following categories of variables: .Variable types in Process Designer You can use the variable types provided by the system toolkits. each value is typed as a string.13. A list of all the base types is provided further in this topic.Base types . Accepts either true or false as values. 475 . During Process Designer installation. or you can create custom business objects. and before the variable is entered into the symbol table. Allows date and time formats to be entered into the variable. The user enters a time. . a Customer structure might contain elements such as lastName. homeNumber. If the predefined business objects provided in the system toolkits do not represent your needs. Parent topic:Business objects and variables Related information: JavaScript API in Process Designer 476 . For example. streetAddress. Custom variable types Custom variable types are defined using business objects. A structure regroups business data that is related to the same subject. firstName.Structure To use a structure type. you can create your own business objects. you need to create a custom structure type and define its properties. system. Process Designer uses namespaces to organize these objects and their methods. When a running process instance or service reaches an exit point.Variable scope in Process Designer In IBM® BPM. A variable that is defined as a Shared Object may persist its values at these boundaries. Available namespaces Namespace tw tw.org tw. the variable values and references may be propagated to variables within that activity. all variables declared for a business process definition (BPD) or service are local variables. All Process Designer variables are JavaScript objects. you can use a variable of the same name in a nested BPD or service and there are no conflicts at run time.object tw. See Declaring and passing variables for more details. Local variables are only accessible to the currently executing process instance or service. the variable's value or references may be propagated to the calling process instance or service.system tw. When a running process instance or service encounters an activity.local tw. Multiple variables may reference the same object. A variable contains a value or references an object.epv tw. The following table describes the namespaces most commonly used during process design and development: Table 1. Because variables are unique to an individual BPD or service.env Description Top-level Process Designer namespace Access Process Designer JavaScript objects and business objects (variable types) Access and update BPD and servicelevel variables Access system features and functionality Access security functionality Access exposed process values (EPVs) Access environment variables Parent topic:Business objects and variables Related information: Setting variables in pre and post assignments Creating exposed process values (EPVs) Setting environment variables 477 . The New Business Object window opens. you must have write access to a process application or toolkit in the IBM® Process Center repository.Simple type . .name = "".Complex type . Then. In the Name field. When you create a business object in a process application. For example.local. case types. 4. If you do initialize a simple type that uses the new keyword. Note:Case management functions are only available if you have IBM BPM Advanced with the Basic Case Management feature installed. Time. Access to process applications and toolkits is controlled by users who have administrative rights to the repository. then you receive a runtime error.Case runtime behavior affects some string 478 . Alternately. . 5.Creating business objects When no system data toolkit variable types or business objects match your specifications. Integer. you can create a business object by clicking New when you create a variable. select the type of your business object and specify a validation if you want. Before you begin To complete the following steps.Creates a new complex business object by specifying the parameters for the structure. you see definition types. Select a type from the Definition type list. Under Behavior.myListOfComplexTypes[0]. 2. and services in the process application. type a name for the custom business object and click Finish. you might want to limit the number of characters for a String type. Date. In the library. An example of initializing a primitive type before use is tw.If you selected Simple type. you can create a custom business object by using a base business object or by defining a new complex structure.Creates a new simple business object that is derived from one of String. open your process application. create or store the custom object in a toolkit. Decimal. In Process Designer. About this task In IBM Process Designer. A simple type that is created with the business object editor cannot be initialized before use with a business process or service unlike a complex type.. If you want to share a custom business object across process applications. or Selection. Procedure 1. Complex structure types that contain primitive types must initialize the primitive types before use. . that object is available for all business processes. beside Data click + and select Business Object to create a new business object. you can create custom variable types called business objects. create a dependency on that toolkit from the process applications that require the variable. Remember: Names of business objects are case-sensitive. 3. If your application requires a large string. therefore. Parent topic:Business objects and variables Related information: JavaScript API in Process Designer JavaScript variable types in Process Designer Business object advanced properties 479 . applications change and business objects. 7.Business objects. . can produce unexpected results. 6. Save your business object. if you want. an attribute. You can also order the parameters. or a variable. their attributes.properties.Business object advanced properties The advanced properties for business objects lets you customize the serialized XML representation of the business object. and variables that are renamed With time. Renaming. add the parameters and a description of each one. . Fixed (always same length) becomes a maximum length. attributes. which can be helpful when an application needs to use current data. an attribute or a variable and see the impact that renaming causes.If you selected Complex type. use the Range property and set a large maximum length. None (unlimited in length) defaults to a maximum of 64 characters. Select the Shared Object check box if the business object and its values must be accessible to other instances at run time. . use the rename function. However.Shared business objects A shared business object's values are accessible to other instances at run time. many parts of a business process might reference or have a dependency on a business object. You see a warning that states this limit when you select this property. . This XML representation is used by external systems when a business object is part of an exposed web service. and variables might be renamed. To rename a business object. Shared business objects only apply to a complex structure type. . the shared business object is deleted if the task instance is deleted. When users trigger a boundary event.The data within a shared business object is shared between business processes and tasks.mySharedBusinessObject(sharedBusinessObjectKey).The shared object is created . Because a shared business object is a different type of business object. . . The data within a shared object is persisted to the database when: . the shared business object is connected to the activity's task instance.myVariable. such as a web service. . It should reference the new output shared business object.Shared business objects allow concurrent modification. The result is your shared business objects will remain in the database until the factory business process is deleted. you should note its special considerations.If the shared business object is created within a human service that can be started and that activity is not bound to a business process instance. tw. . .Shared business objects A shared business object's values are accessible to other instances at run time. get the unique identifier key and then load the instance using the key.An output shared business object for an external service. When the business process instance is deleted (for example. . it is based on a factory method pattern).A shared business object uses database resources.local.Each shared object is logically connected to the business process instance that created it.The JavaScript method save() is performed on the shared business object.If you clear the Shared Object check box at a later point in time. . For example.Best practice for shared business objects: If you want to create shared business objects that have a long lifetime. your application should not reference the input shared business object expecting an updated value if your application is working with an external service or an Advanced Integration Service.If a shared business object is deleted from the database. . which can be helpful when an application needs to use current data. For example in the following code. To load the data.object. when you delete a business process instance that was running in the Inspector). two users can view and modify the same shared business object instance in a human service. the business object will no longer be accessible to other instances at run time. the data of the shared business 480 . the behavior of the tasks or processes that reference the shared business object is undefined.metadata("key").myVariable = new tw. sharedBusinessObjectKey would be obtained by running tw.The task is persisted to the database . the shared object data in the database is also deleted. Therefore. In such cases. . and an Advanced Integration Service will return a new and typically updated copy of the original input shared business object. you may want to design a business process that acts as a factory (that is.local. You can send data from one process to a second process using a Message Event or by loading the data into the second process using the unique key of the shared business object. object. sharedObject. Only the fields that each user modifies are saved. tw.taskId). Parent topic:Creating business objects 481 . sharedObject. as shown in the following example.sharedObjectKey = sharedObject. a server script that makes modifications to shared business objects. In addition to multiple users. you can have a situation with automated steps.taskId: " + sharedObject2. log.SharedObject().local. You can create and retrieve the shared business objects you have created by using a key. In this case.metadata("key").save().SharedObject(tw. // Create key for shared object tw.taskId = "init".object instance is saved. // Create shared object var sharedObject = new tw. both changes are saved.info("sharedObject2.info("sharedObjectkey: " + tw. Therefore.object.SharedObject is the shared business object.local. log.sharedObjectKey). If both users modify the same field.object.local. // Retrieve shared object by key var sharedObject2 = new tw. the last user’s update is saved. if the two users modify different fields.sharedObjectKey). for example. the pane shows the business processes and services that reference the business object. change the business object name in the New name field. many parts of a business process might reference or have a dependency on a business object. and variables that are renamed With time. 3.Business objects. you have the option of clearing Update references. check all the artifacts that you expected to be updated. which are called attributes. none of the references to the attribute are updated. you see the references to that business object in the subsequent Refactor window. follow these steps: 1. when you click OK . therefore. can produce unexpected results. To rename a business object. an attribute or a variable and see the impact that renaming causes.object. new tw. In the Refactor window. and variables are contained in the following sections. Afterward. However.object. In that case. By default. select Data from the navigation. or a variable. 2. a message says that to refactor the value press Alt + Shift + R. however. To rename a business object. and variables might be renamed. By default. If you want to analyze the list later. Change the attribute name in the New Name field. particularly in JavaScript sections. Select Rename from the menu. their attributes. Right-click the business object that you want to rename. Select the business processes and services that you want updated and click OK. an attribute. 482 . In the window that opens. you have the option of clearing Update references. Select the attribute in the Parameters list that you want to rename. When you change the name in the Name field. you can copy the names of the business processes and services to a clipboard by clicking Copy To Clipboard. Procedures for renaming business objects. Click Data and double-click the business object in the menu that contains an attribute that you want to rename.OldBusinessObject or new tw. Renaming business objects and attributes To find business objects. when you click OK. Business objects are themselves composed of other variables. If there are no references. follow these steps: 1. In that case. you see the references to the attribute in the subsequent Refactor window.OldBusinessObject. continue to click OK to rename the business object. The refactor function updates all fully qualified references that are instantiated with the keyword new for the old business object and old business object lists. their attributes. To rename an attribute. However. Renaming. none of the references to the business object are updated.listOf. 2. However. for example. 4. use the rename function. the pane is blank. attributes. applications change and business objects. Pressing this combination starts the Rename window. You can rename attributes of a business object and the rename function shows you the business processes and services that are affected. In the first example. however. tw. id would be updated.local. When you start the refactor window. . customer.The object is assigned to a fully qualified business object that is instantiated with the keyword new or to any ancestral attribute of the object. continue to click OK to rename the attribute. the reference is not selected to be refactored. Renaming a variable can affect a reference to it within the same business process or service. 4.Property names are not updated when the square bracket notation is used. businessobject.To be listed as selectable for refactoring. An example of an ancestral attribute that would be refactored is GreatGrandparentBusObj.ParentBusObj. firstname. .busobj.object.name = "John". check all artifacts that you expected to be updated. If you refactor a business object and one of its references is being edited by another user.name. Select the business processes and services that you want updated and click OK. in the following code. Renaming a variable Variables are found within a business process or a service. the pane is blank. would not be updated: customer['firstname'] = "John". In the next two examples. for example. .GrandparentBusObj. var businessobject = new tw. . name would be updated. In the Refactor window. var customer = tw. The refactor function updates attributes on objects in the following situations: . the business object and the references are unlocked.customerInfo. Limitations: . Afterward. If there are no references.3. the pane shows the business processes and services that reference the business object.JavaScript code in Coaches is not updated. When the refactor operation is finished. as are any references that are selected to be refactored. renaming a variable does not affect another business process or service.id = 1234. follow these steps: 483 .customerInfo.The object is assigned to a local variable that does not have an ANY type or to any ancestral attribute of the object. In other words. the business object that is being refactored is locked.Refactoring does not update the binding when the business object parameter name is changed. particularly in JavaScript sections. A message specifies the user who is editing the reference.id = 5678.BusinessObject().local. You can copy the names of the business processes and services to a clipboard if you want to analyze the list later by clicking Copy To Clipboard. the business processes or services must reference the business object with the variables or variable fields that are found in the Variables tab. To rename a variable. 1. Click the Variables tab and select the variable that you want to rename. Change the variable name in the New Name field. a message says that to refactor the value press Alt + Shift + R. 2. In that case. when you click OK. By default. you do not see a subsequent panel where you select references or are shown no references. all references to the variable are updated. Parent topic:Creating business objects 484 . When you change the name in the Name field. Pressing this combination starts the Rename window. none of the references to the variable are updated. Unlike renaming a business object or attribute. However. you have the option of clearing Update references. this would mean testing those web services after your change. In this section. for example. The following properties are discussed: Advanced properties Anonymous typeElement nameElement namespaceExclude from XMLNamespaceType name Advanced parameter properties Anonymous list typeExclude from XMLList item nameList type nameMaximum occurrencesMinimum occurrencesNameNamespaceNil lableNode TypeOrderTime zoneType nameType namespaceWrap list Anonymous list type This property sets whether the type of the wrapper is named or anonymous. A change will only affect this particular business object. Only change a value if you are an advanced user who has a need to override a value. you should test the Advanced Integration service. This property is available only when the parameter is a list and the wrap list property is true. saving that configuration of the business object and then clicking View XML Schema to see the XML Schema Definition (XSD) describing the XML representation of the business object. The advanced properties used for serialization purposes are automatically created with appropriate values when you create a business object or import a WSDL file with business objects. You should be very knowledgeable of all the standard XML elements as defined by the W3C's XML Schema. It is recommended that you leave these serialization values as they are. If you are using the business object in inbound or outbound web services. If you had a process application with 100 business objects and you wanted to override an element such as the target namespace in the XML representation for all business objects then you would need to make 100 changes. You should also have read the web services compatibility topic and the XSD generation pattern for business objects topic which are linked to at the end of this topic. If you are using Integration Designer and your business object is used in an Advanced Integration service. each property has a description and some contain examples of values that you might change using customization so that you understand the behavior of the using the customization tool. This XML representation is used by external systems when a business object is part of an exposed web service. Any change to serialization values should be tested. The customization is done by selecting and changing a property. These topics specify restrictions that apply to XML schemas interacting with this product and within this product.Business object advanced properties The advanced properties for business objects lets you customize the serialized XML representation of the business object. 485 . The default value is false (named type). If you have read the XSD generation pattern for business objects topic you will also know that the true value is not honoured by the generator.w3.org/2001/XMLSchema" xmlns:tns="http://EH" targetNamespace=http://EH" elementFormDefault="qualified" attributeFormDefault="unqualified"> 486 . Your output should be similar to the following sample. However a type could define some instance fields that you might not want to serialize to an XML representation. if you only need to reference a type once then there is considerable coding overhead. Use the default value unless it is strictly necessary to make a change. Use the default value unless it is strictly necessary to make a change. if you were use the example from the anonymous type property and exclude employeeNumber. Element namespace This property sets the namespace of the container element. Click View XML Schema. the output is like the following example:<xs:schema xmlns:xs="http://www. Exclude from XML In most cases you would leave this setting in its default value of false.org/2001/XMLSchema" xmlns:tns="http://EH" targetNamespace=http://EH" elementFormDefault="qualified" attributeFormDefault="unqualified"> <xs:element name="employee"> <xs:complexType> <xs:sequence> <xs:element name="employeeNumber" nillable="false" type="xs:string" minOccurs="0" maxOccurs="1" /> <xs:element name="firstName" nillable="false" type="xs:string" minOccurs="0" maxOccurs="1" /> <xs:element name="lastName" nillable="false" type="xs:string" minOccurs="0" maxOccurs="1" /> </xs:sequence> </xs:complexType> </xs:element> </xs:schema> Element name If the anonymous type property is set to true. You may also not want to serialize a lot of data when you know the web service could take some of the data and calculate values itself thus improving performance by reducing the data transferred. To exclude a business object or parameter from the XML representation.w3. For example. an InvoiceType. an instance field that has no equivalent in XML as it refers to an internal running process. which will include your business object or parameter in the XML representation. this property places the anonymous type under an element with the specified name. An anonymous type is used for these cases of a single reference. The default value is false. select Exclude from XML and select true. To specify the value for an anonymous type.Anonymous type Schemas can be built with sets of named types. However. Then elements can be declared such as invoiceCanadian that reference those types. Save your work. for example. For example. Anonymous types can cause difficulties as discussed in Web services hints and tips: avoid anonymous types. Save your work. select Anonymous Type and select true or false. <xs:schema xmlns:xs="http://www. Click View XML Schema. Click View XML Schema. Use the default value unless it is strictly necessary to make a change. Use the default value unless it is strictly necessary to make a change. this property changes the target namespace. Maximum occurrences This property sets the maximum number of times that the parameter occurs. This property corresponds to maxOccurs in the XML schema. List type name This property sets the name of the complex type that encapsulates a wrapped list. Use the default value unless it is strictly necessary to make a change. The default value is 0. Save your work. This property corresponds to the name attribute in the XML schema. This property corresponds to minOccurs in the XML schema.<xs:element name="employee"> <xs:complexType> <xs:sequence> <xs:element name="firstName" nillable="false" type="xs:string" minOccurs="0" maxOccurs="1" /> <xs:element name="lastName" nillable="false" type="xs:string" minOccurs="0" maxOccurs="1" /> </xs:sequence> </xs:complexType> </xs:element> </xs:schema> List item name This property sets the name for a wrapped list item. select Namespace and enter the target namespace you prefer. Namespace If you set the namespace for the business object. Your output should be similar to the 487 . You might want to change the target namespace if you imported a WSDL file and the target namespace for your business object was changed on importation. The target namespace defines explicitly the elements that belong to this instance of the namespace. Minimum occurrences This property sets the minimum number of times that the parameter occurs. Use the default value unless it is strictly necessary to make a change. For example: http://www. This property is available only when the parameter is a list and the wrap list property is true.com/employees . The default value is 1. The property is therefore valid only for a wrapped list that is not anonymous.mycorporation. Name This property overrides the name of the serialized parameter with the name that you specify. The default value is the name of the type of the list elements. it overrides the serialized element namespace for that parameter. Use the default value unless it is strictly necessary to make a change. To rename the target namespace. The default value is the name of the parameter. If you set the property for a parameter. you might want to change the order if the 488 . so you do not need to set it explicitly. Your output should be similar to the following sample. select Node Type and select Attribute. However. A discussion of these types can be read in Principles of XML design: When to use elements versus attributes. Node Type Nodes in an XML document can be defined as elements or attributes.com/employees" elementFormDefault="qualified" attributeFormDefault="unqualified"> <xs:complexType name="employee"> <xs:sequence> <xs:element name="employeeNumber" type="xs:int" minOccurs="0" maxOccurs="1" nillable="false" /> <xs:element name="firstName" type="xs:string" minOccurs="0" maxOccurs="1" nillable="false" /> <xs:element name="lastName" type="xs:string" minOccurs="0" maxOccurs="1" nillable="false" /> </xs:sequence> </xs:complexType> <xs:element name="employee" type="tns:employee" /> </xs:schema> Nillable This property determines whether the parameter can have a null value. <xs:schema targetNamespace="http://www. you can set it to use an attribute. Click View XML Schema.following sample. Save your work. <xs:schema targetNamespace="http://EH" elementFormDefault="qualified" attributeFormDefault="unqualified"> <xs:complexType name="employee"> <xs:sequence> <xs:element name="firstName" type="xs:string" minOccurs="0" maxOccurs="1" nillable="false" /> <xs:element name="lastName" type="xs:string" minOccurs="0" maxOccurs="1" nillable="false" /> </xs:sequence> <xs:attribute name="employeeNumber" type="xs:int" /> </xs:complexType> <xs:element name="employee" type="tns:employee" /> </xs:schema> Order Order explicitly sets the order of the complex type's elements.mycorporation. an element type is used which is the default. Use the default value unless it is strictly necessary to make a change. However. To change the type to an attribute. Usually you would leave the order in the XML representation of the business object exactly as it is in the business object editor. In most cases. Use the default value unless it is strictly necessary to make a change. A list is an array and it is specified when List is selected as an attribute. A wrapper type can be anonymous and the name of the list items can be overridden.external web service changed and required the elements to be presented in a specific way. Wrap list This property determines whether to create an array wrapper type to contain a list. <xs:schema targetNamespace="http://EH" elementFormDefault="qualified" attributeFormDefault="unqualified"> <xs:complexType name="employee"> <xs:sequence> <xs:element name="lastName" type="xs:string" minOccurs="0" maxOccurs="1" nillable="false" /> <xs:element name="firstName" type="xs:string" minOccurs="0" maxOccurs="1" nillable="false" /> <xs:element name="employeeNumber" type="xs:int" minOccurs="0" maxOccurs="1" nillable="false" /> </xs:sequence> </xs:complexType> <xs:element name="employee" type="tns:employee" /> </xs:schema> Time zone This property sets the time zone to use when serializing a date parameter. suppose the order of an employee complex type is employeeNumber. Use the default value unless it is strictly necessary to make a change. firstName and then employeeNumber. firstName and lastName and you needed to change it to accommodate a web service order of lastName. The other valid values are SERVER and UTC. You might use this field if you wanted to encapsulate the array. The default value is CLIENT. Click View XML Schema. The property is not used in WSDL generation or schema creation but it is used to display date and time values. For example. which means that the list is not wrapped. To change the order of a complex type's elements. The default value is false. Save your work. You would set employeeNumber to 2. 489 . Type name This property sets the qualified name of the type for the business object or parameter. Use the default value unless it is strictly necessary to make a change. If you have not selected List for a variable. select each element and add a number to the Order field to specify the order you want in the XML representation. firstName to 1 and lastName to 0. Your output should be similar to the following sample. Type namespace This property overrides the type namespace of the serialized XSD type with the namespace that you specify. this field and other fields with list in their name are disabled. Parent topic:Creating business objects Related reference: Web services compatibility XSD generation pattern for business objects 490 . and General System services. the local variables with the same shared object key are refreshed from the data store. . to pass variables to an activity or a step you have to set the input and output data mapping. declare variables and business objects to receive the values of the variables of the main BPD. and between services and services. . . At each process. service or message event boundary. between processes and services. . You can use the Activity Wizard to create Human.Declaring variables for a BPD or a service For each business process definition (BPD) or service that you create. The variables are local to a business process definition (BPD) or service. Rule. you must properly declare the variables and pass them to the linked processes. See Shared business objects for information about shared objects. that is. their types should be compatible. business data in Process Designer is passed between processes and linked processes. When you do. Pass the variables from the linked processes and services back up to the main BPD as outputs when you want the main BPD to be aware of changes made to the variables in the linked processes or services. Note: When you use the Activity Wizard to create a service to implement an activity. 4. 2. a string variable in a process can only be passed to a linked process if this linked process has a string variable declared as an input variable. the Activity Wizard automatically declares the variables for the resulting service and completes the data mapping for the activity.Declaring variables for a subprocess Subprocesses and event subprocesses can access the variables of the process 491 . select the Shared Object check box. services. Declare variables at the BPD level. An alternative form of propagation is to define the variable type as a shared object when you create or edit your business object. you must declare variables to capture the business data that activities in that BPD or steps in that service use. When passing variables from a process to a linked process.Declaring and passing variables Variables capture the business data that is passed from step to step in a process. and message events. The general procedure for passing variables is: 1. You cannot reference a variable from another business process definition or service. Variables contain the values or references to business data. The values of a variable designated as a shared object are persisted to a data store. Pass those variables as inputs to the linked processes and services that require them for their implementation.Mapping input and output data for an activity or step In Process Designer. For each linked process and service. For example. 3.How variables are passed in Process Designer Using variables. you can pick the variables from the main BPD to use as input and output. To propagate the business data values and references. They can also have their own variables that are only relevant within the context of the subprocess or event subprocess and any subprocesses or event subprocesses they might contain. Parent topic:Business objects and variables 492 . .Testing declared variables and data mapping with coaches When you declare and map variables in your BPD. you can test the mapping between activities by using coaches and running your BPD in the Inspector.they are contained in. Variables between BPDs and services are passed by value. 493 . Therefore. The BPD and services will each contain a separate copy of the business object. . most of the time the same object is passed from location to location.When the first service completes. Also. . Variables capture business data. the values of the shared object will automatically be persisted to the data store. . the shared object values will be automatically loaded from the data store. a String) then the variable contains a value of the business data. When a variable is passed by value from a BPD to an underlying service. For example. between processes and services.Most data interactions in a process are passed by reference (from BPD to BPD or from service to service). the service that changes the variable passes the changed complex variables back to the BPD as output variables. business data in Process Designer is passed between processes and linked processes.If a variable is defined as a shared object. When the second service starts. and between services and services. changes to that object happen at all levels. Table 1.How variables are passed in Process Designer Using variables. If the business data is a complex type then the variable is a reference to an object containing multiple values. Variables can be passed by reference or by value.Variables passed by value .Variables passed by reference .Variables that are shared objects . a shared object is passed by value from a BPD to two different services. How variables are passed From Business process definition (BPD) activity BPD activity To Service Type Simple Pass by Value Service Complex BPD activity BPD activity Linked BPD Linked BPD Simple Complex Service Service Nested service Nested service Simple Complex Value (the BPD and Service have separate copies of the business object) Value Reference to the same business object Value Reference to the same business object . If the business data is a simple type (for example. its values are refreshed from the data store before use. as described in the following table. The inner BPD passes the . mapped back to the variable of the inner BPD . and then passed back.Always use an identical name and data type for a set of input and output variables for data that is passed in. BPDs and services have references to their variables. . when a complex variable is passed from the service to a BPD.Outer BPD -> NVP1 Inner BPD -> NVP3 Changes made to NVP3 are not reflected in NVP1.. and nested services. changes made to the inner BPD are not reflected in the outer BPD. services.pair to a service.pair. See Creating custom business objects in Process Designer for information on shared objects. although the output declaration is not required because complex types are passed by reference.The service exits and outputs the . NVP1. When the service changes the values of the existing complex variable.If the variable is a simple type. tw.Outer BPD -> NVP1 Inner BPD -> NVP1 Service -> NVP2 . .If the variable is a complex type. Therefore. follow these guidelines: . .pair reference to an inner BPD: Outer BPD > NVP1 Inner BPD -> NVP1 Changes to either BPD affect the other BPD. and a reference of the copy is passed to the service. The outer BPD passes its . The parent BPD is not updated until the child BPD has finished. Also. Parent topic:Declaring and passing variables 494 . the changed values are passed back to the BPD by replacing the entire complex variable with a deep copy from the service. If the replaced variable was originally passed by value from an outer BPD. If you want a service to modify a top-level variable in a BPD. When complex variables are passed from a BPD to a service. NVP3. use an embedded JavaScript to store the service result in a temporary variable and copy its members to the original variable. A copy of NVP2 is created. that points to a NameValuePair object. declare the variable as an input and an output in linked BPDs. Similarly. declare the variable as an output so that other developers will know that the linked BPD. a deep copy of the variable is transferred from the service space to the BPD space. the values of these objects are updated by the data store. the inner and outer BPDs no longer access the same variable.pair. NVP2. Recommended guidelines Because of how Process Designer handles variables. and the service gets a reference to the copy.Example . and a reference is passed back to the inner BPD. processed. service.local. A copy of NVP1 is made. .An outer BPD has a reference. This allows the running services to operate on current data. or nested service returns a complex variable.So even though the BPD and two services reference separate objects. and the BPD gets a reference to the copy. declare the variable as an input. a deep copy of the variable is transferred from the BPD space to the service space.pair. 495 . B.Note: Variable names start with a lowercase letter. 2. Optional: If you want your variable to be an array. Do not use underscores or spaces in variable names. Procedure If you want to add an exposed process variable. input. or output variable. D.Declaring variables for a BPD or a service For each business process definition (BPD) or service that you create. or output variable. and then select the EPV from the list. Variables available for addition to business process definitions Variable Private Input Output Exposed process variable (EPV) Description Local variables that are used only within the process. click Add Private. click Link EPV. input. Type a variable name in the Name field. with subsequent words capitalized. A process instance identifier variable can be a private. Custom business objects that you created are also listed. Optional: Type a description of the variable in the Documentation field. About this task You can add the following variables to your BPDs: Table 1. select Is List. C. Special type of variables that you can create to set or alter values while instances of a process are running. open the IBM® Process Designer desktop editor. Click Select next to the Variable Type field to select the type of the variable. In the Variables tab. Variable that represents output data that the current BPD or service returns to its caller. Variable names are casesensitive. If you want to add a private. Only BPD variables that are marked as process instance identifiers can be used for instance-based correlation of intermediate message events that use the SCA triggering mechanism. complete the following steps: 1. Before you begin If you are declaring variables for a BPD. for example: myVar. and can be a simple or complex variable type. 3. or Add Output to create the corresponding variable. Open your BPD or service diagram in Process Designer. Variable that represents input data passed to the current BPD or service. you must declare variables to capture the business data that activities in that BPD or steps in that service use. In the Details section: A. Add Input. 496 . 8. in the Business Data section.4. 7. by mapping input and output variables. While it is possible to mark any variable as process instance identifier. use the same search alias if you want search results to include all related processes. select Has Default. and are indicated in variable selection dialogs by the text [Identifier]. Because variables that are selected as process instance identifiers can be written to only once. in the Performance Tracking section. and enter the value in the corresponding field. 6.Important: The value that is written to the variable must be unique for each instance of the BPD. Optional: To set a default value for the variable. pre-assignments. Writing any value to such a variable more than once causes an error.Tip: The search alias must be unique to the variable type throughout the process server on which the BPD runs. select Visible in Process Portal. it is advisable to use a variable for this purpose that is not too complex. the variable is marked with an error icon on the Data Mapping tab. Tip: If you clear the selection for a variable that is already used for correlation. Optional: To include the BPD variable in the business data that users can view in Process Portal. If a variable is used in parent and nested processes. To save the configuration. Optional: To include the BPD variable values in the data that is collected and used to create reports. data mapping. you must mark it as a process instance identifier. be careful during initialization. and can be dragged in the layout window. Parent topic:Declaring and passing variables Related information: Using Service Component Architecture to interact with processes Data tracking considerations Mapping input and output data for an activity or step Creating exposed process values (EPVs) 497 . the variables are directly available inside the diagram. and post-assignments to avoid it ever being written to twice for an instance. Variables that are marked as process instance identifiers can be selected to be used for correlation. click Save in the main toolbar. 5. In the Process Identification section. and type an alias in the Alias field. select Variable is used as Process Instance Identifier. If you have a coach in the diagram. select Track this Field. What to do next The BPD or service includes variables that can be passed to activities or services. To declare a BPD variable as a secondary process identifier. in the Default Value section. and then click the Data Mapping tab in the properties. Case management functions are only available if you have IBM BPM Advanced with the Basic Case Management feature installed. to pass variables to an activity or a step you have to set the input and output data mapping. Procedure 1. The following procedure describes how to map both input and output data for an activity or a step. Similarly.For receive events that are triggered using an undercover agent (UCA). or the service in the case of a step. Click the activity in the BPD diagram or the step in the service diagram. Tip: If a selected variable is subsequently changed to not be a process instance identifier. Before you begin You must have a business process definition (BPD) that contains a set of declared variables and an activity. only variables that are marked as process instance identifiers can be used for correlation. mapping input and output data is applicable only if the client-side human service is used within a BPD or a case type activity. an activity or step may only require input or output data and not both. For receive events that are triggered using a Service Component Architecture (SCA) service call. you must set the input and output mapping for each step included in the service. Also.Mapping input and output data for an activity or step In Process Designer.Restriction: In the case of a client-side human service. The activity or step must implement a service or linked process which also contains a set of declared variables that match the ones in the main BPD in the case of an activity. About this task When developing processes in Process Designer. Note: This task is not relevant if you use the Activity Wizard to create a service to implement an activity. if you have a service. you must set the input and output mapping for each activity included in a BPD so that the variable values received and generated by the subprocesses and services that implement the activities map to the variables from the main BPD. Data mapping is not applicable if the client-side human service is used for a dashboard or a case instance. The Data Mapping tab displays the variables that are available from the service implemented in the activity or step. an error icon is displayed by the variable on this tab.Note: Auto-mapping works only when variable names and 498 . Open the diagram of your BPD or service. 3. click the Auto-map input properties with variables from service icon ( ) in both the Input Mapping and Output Mapping sections. 2. both identifier and non-identifier variables can be used for correlation. or a service that contains a set of declared variables and a step. Depending on the logic of your BPD or service. . To complete the data mapping. What to do next The data mapping is complete. Parent topic:Declaring and passing variables Related information: Testing declared variables and data mapping with coaches 499 . If your variable is a shared business object then the output mapping from the activity or step is not required. and then passed back. and you can test it.types match exactly. processed. You should always use an identical name and data type for a set of input and output variables that are passed in. Click Save to save the configuration. 4. Go to the Variables tab. if you are modeling the Get Customer Order subprocess of a larger Customer Order Handling process. 4. click Add Private. as are any private variables declared in the parent BPD. so it is a private variable within the subprocess only. data type. with subprocesses contained within other subprocesses. For example. passing values between any subprocess activities that might require them.Declaring variables for a subprocess Subprocesses and event subprocesses can access the variables of the process they are contained in. Data that is used only within the subprocess should be captured in private variables declared in the subprocess activity. Expand your subprocess or event subprocess by double-clicking the activity in the parent BPD. If the data is only used within the context of process execution. variable names must be unique throughout the entire subprocess hierarchy. 500 . Complete the details of the new variable. For example. and description. 3. In addition. You can access these variables from within your subprocess or event subprocess. If the data needs to be passed into or out of the process. create these variables as private variables. this alias must be unique within the top-level process and across all subprocesses and event subprocesses under the same top-level parent. This data is not needed outside of this part of the larger Customer Order Handling process. Before you begin If your subprocess uses business data that is also used in the top-level process or in other subprocesses or event subprocess under the same top-level parent. Note: Variable names declared in a subprocess or event subprocess cannot be the same as variable names declared in its parent process. The contents of your subprocess or event subprocess are visible in the editor. In the Variables tab. create your variables as input or output variables in the top-level process. you might need to access the Customer Account variable that is declared in the parent process. This variable is visible to the subprocess or event subprocess and any embedded subprocesses or event subprocesses. Procedure 1. The new private variable is created. They can also have their own variables that are only relevant within the context of the subprocess or event subprocess and any subprocesses or event subprocesses they might contain. The input and output variables declared in the top-level process are visible. if you specify a search alias to use for business data in Process Portal searches. 2. the Get Customer Order subprocess might need to use a private variable that is used to authenticate the customer service representative onto the ordering system. Create private variables for any data that is used only within the context of the subprocess or event subprocess and any subprocesses it contains. including a name. but is not accessible by the parent BPD. If there are multiple layers of embedding. declare the variables in the top-level BPD. disabling autotracking in the parent BPD does not disable autotracking in the subprocess or any subprocess that is contained within that subprocess. Therefore. C. After enabling autotracking and specifying the variables to track. Under Performance Tracking. or using the Activity wizard. ensure that Enable Autotracking is enabled for the subprocess. In the Tracking tab. In the Variables tab. Parent topic:Declaring and passing variables 501 . you can enable automatic tracking of variable data for the subprocess. To capture information about your subprocess data at run time. If you have activities inside your subprocess that are implemented by services. A. B. you will need to map the input and output data required by these services. activities within your subprocess or event subprocess can use these variables to capture business data. either manually through the Data Mapping tab. select the Track this Field check box. see Mapping input and output data for an activity or step. From the IBM BPM main menu. D. save the process and send your newly defined tracking requirements to the Business Performance Data Warehouse. select the variable that you want to track.5. What to do next Now that you have declared your private variables. For more information about mapping input and output data. select File > Update Tracking Definitions. This setting is independent of the setting for the parent process. Save by clicking the Save icon. Procedure 1. D.Note: If prompted to switch to the Inspector. click Yes. Before you begin Make sure: . activities in the participant lane are assigned to the All Users group. Remember that variable types and name must match. About this task This task is an example of how you can test your JavaScript variable mechanics from the graphic interface of Process Designer by passing a variable from the BPD to an activity. open the BPD that includes at least an activity for which you established data mapping. C. B. click the Refresh icon ( ). if you want to test data mapping between 2 activities that implement their own services.The data mapping is set as needed. The task runs and the coach displays the values of the local variables in a browser window. add a coach to each service and drag all the variables (input and output) available into it. 3. In the Process Instances tab in the Inspector. You can also test your variable mechanics through the JavaScript text box inside your services or activities.Your BDP contains all the elements that pass and retrieve variables. Repeat the previous steps and check that the current variables displayed in the browser reflect the changes you made in the previous coach. 5. Modify the values of the variables to see whether the changes will be passed on to the next task for which you mapped the data. The task generated by the following activity in the BPD is displayed. 502 . 4. For example. run the current task by clicking the line of the table on the right side of the screen indicating Received in the Status column and then click the Run the selected task icon ( ). 2. To validate your changes click OK. E. The browser closes. By default. add a coach to it and add the controls representing each variable inside the coach. For each activity you want to test. For example. select the user account that you want to use to run the task. When prompted. In the Inspector toolbar. 2 activities that transfer data to one another. you can test the mapping between activities by using coaches and running your BPD in the Inspector. In Process Designer.Testing declared variables and data mapping with coaches When you declare and map variables in your BPD. The values that are displayed depend on the data mapping of the current task. Click the Run Process icon ( ) to run the BPD in the Inspector. Check your data mapping with the coaches: A. . your data mapping is properly set. review your data mapping settings.What to do next If the data you modify in a task is displayed in the following task of your BPD. If the data should match but does not. Parent topic:Declaring and passing variables Related information: Mapping input and output data for an activity or step 503 . com"> <xsd:complexType name="MemberBenefit"> <xsd:sequence> <xsd:element minOccurs="0" name="BenefitMessages" type="bons1:BenefitMessagesWrapper"> </xsd:element> </xsd:sequence> </xsd:complexType> <xsd:complexType name="BenefitMessagesWrapper"> <xsd:sequence> <xsd:element maxOccurs="unbounded" minOccurs="0" 504 .com" xmlns:tns="http://member. in the following code the BenefitMessagesWrapper complex type when imported would create a dummy business object that serves no purpose since the MemberBenefit business object has the declaration defined for it under the BenefitMessages property.XSD generation pattern for business objects When you create a business object. which could cause confusion. In Process Designer. The schema you see by clicking View XML Schema may not be an accurate representation of the XSD as seen in Integration Designer. For example. which is also referred to as a custom variable type. for clarity you may want to delete it.ourgroup.ourgroup. note that the Advanced Parameter Properties Type Name and Type Namespace will be used as opposed to the values specified by the referenced business object. the Integration Designer user will see two complex types. These imports may result in compile errors on some of the generated artifacts when they in turn are brought into Integration Designer. specified in Advanced Parameter Properties using the wrap list property. In particular. an XML Schema Definition (XSD) is generated. a dummy business object for the wrapped array element will be created in addition to the referencing business object having the same definition in the Advanced Parameter Properties. which means that a named. This may be true for the properties that were specified as a result of an import of a WSDL or XSD file. This property is not honoured by the generator. <xsd:schema targetNamespace="http://member. No synchronization with Integration Designer is done.ourgroup. For wrapper array types. You should be careful when you use the properties in the Advanced Properties and Advanced Parameter Properties sections as the generated schema may not be as you expected. An anonymous type can be specified in the Advanced Properties section when creating a business object. when you import a web service that has a wrapped array element definition.com" xmlns:bons0="http://member. Although it can be present as a business object. Understanding the generation rules and some suggestions for business object creation can be helpful when your business objects will be used with IBM® Integration Designer. complex type will be generated. If you do not delete it. the generated code is inline with the business object. A type without a name is called an anonymous type. name="BenefitMessageObject" type="bons1:BenefitMessageObject" /> </xsd:sequence> </xsd:complexType> <xsd:complexType name="BenefitMessageObject"> <xsd:sequence> <xsd:element minOccurs="0" name="field1" type="xsd:string" /> <xsd:element minOccurs="0" name="field2" type="xsd:string" /> </xsd:sequence> </xsd:comple Parent topic:Business objects and variables 505 . 3. Results Your code is run when you run your process. groups and roles All the variables you declare in Process Designer are JavaScript variables. You can use them inside service definitions and also in expression evaluations inside JavaScript code snippets.The system data available at run time .The performance information . If you selected an activity. 4.Using JavaScript in BPDs You can use JavaScript in many business process definitions (BPDs) in Process Designer to improve the behavior of your model. 5.The design-time aspects of Process Designer . Click to select an activity in the BPD diagram or a server script component in a service. select JavaScript from the drop-down list. in most cases it is best to create a service that includes a server script component and then use the service to implement the activity. Parent topic:Business objects and variables Related information: Managing external files 506 .Users. While Process Designer supports using JavaScript to implement an activity. 2. Declare your BPD-level variables through the graphic interface. you can write your code in an external JavaScript file and import it as an external library. in the Implementation section. you can write JavaScript to implement a step in your process and embed that script in an activity. What to do next If you want to reuse your code.The installation status .Serialized and deserialized Process Designer objects . Type your JavaScript code in the Script text box. For example. Procedure 1. Click the Implementation tab in the properties. About this task Process Designer provides a number of JavaScript methods and variables to customize your BPDs and to interact with: . For example: tw. The variable can now store data. For example: tw. . ensure that service level code does not require variables to be in an undefined state if a Coach references these variables. Note: If your complex business object or list includes elements that are complex variables. Because of this initialization.listOf.<businessObject>().<listName>=new tw. the framework does it when the Coach runs. In the diagram area. 3. use: tw. If the human service does not initialize these variables.listOf. Parent topic:Business objects and variables Related information: Declaring variables for a BPD or a service in Process Designer 507 .local.If the variable is a complex object.. What to do next You have initialized your complex variable or list.Initializing complex variables and lists In Process Designer.local. drag a script task from the palette to the canvas. a variable named myVariable of type Requisition or a variable named myList that is a list of string variables. This initialization occurs even if the Coach does not use these variables.myVariable=new tw. declare a variable that is a complex business object or a list.object. you must initialize all complex variables and all lists (arrays) before you can use them in a BPD or service..local.String().myList=new tw. In the Implementation tab. About this task The Coach framework requires that all variables that a Coach or Heritage Coach references are initialized.<businessObject>(). 2. they also must be initialized. For example. Procedure 1.Requisition().<variableName>=new tw. In the Variables tab of your BPD or service diagram. use: tw.object.object.local. initialize your variable using the a JavaScript text area: .object.If the variable is a list. In the Name field. add a variable for each available level. you must be in the IBM Process Designer desktop editor. In the Variable Name field.For example. In the Documentation field. you can create exposed process values (EPVs) to define a set of variables you want to expose to specific users. C. type the name of the variable for the users. with subsequent words capitalized like so: myVar. you can provide this type of flexibility. you may want to enable supervisors to change the allowed amounts for daily expenditures. Before you begin To perform this task. D. if you want to enable users to adjust the dollar amounts that correspond with various levels of approvers for an expense reimbursement process. task assignments. Add one or several variables to the EPV by applying the following steps: A. These variables can be modified by the users while instances of a process are running.The Manage Exposed Process Values page in the Process Admin Console includes a feedback link that uses this email address. For example. and so on. To allow users to send feedback about this EPV.Creating exposed process values (EPVs) In IBM® Process Designer. The New Exposed Process Value window opens. if you create a process to handle expense reimbursement. Variable names are case sensitive. Do not use underscores or spaces in variable names. 3. type a name for the value and click Finish. 4. 2.Note: Variable names should start with a lowercase letter. B. In the Variable Details section. This name appears in the Variable List for this EPV in the Process Admin Console. type an email address in the Feedback E-mail Contact field. The description that you provide here is displayed in the Manage Exposed Process Values page in the Process Admin Console. type the name of the variable for internal processing. In the External Description field. In the Exposed Process Value Variables section. in the External Name field. The EPV configuration view opens. enter a description of the EPV for the developers. This description appears in the Variable List for this EPV in the Process Admin Console. B. click Add to add a variable to this EPV. Procedure 1. 5. enter a description of the EPV for the users. allowing users to adjust specific variable values as constants. In the External Description field. Expand Data and select Exposed Process Value. type the text to describe this variable to users. C. Configure the EPV: A. Open the Process Designer desktop editor. By creating EPVs. thereby affecting the flow of all running process instances. 508 . or the dollar amount that coincides with various levels of approvers. .epv. 7. Results The EPV is created.[epv_name].[epv_variable_name]. click Select. Click Save in the main toolbar to save your changes. Parent topic:Business objects and variables Related information: Creating custom business objects in Process Designer 509 . To select a variable type. you can link it to a BPD or a service.Adding an exposed process value to a BPD When you create an exposed process value (EPV). Optional: In the Default Value text box. You can use the EPV in a decision gateway to control the flow of a process. You can reference the name of the EPV and its variables like so: tw. type a valid default for this variable. In the Exposing section. To enable in-progress tasks to use the updated value of this variable when users edits its value. service. select the In-Progress Tasks Use New Values check box. F. click Select to choose the team whose members can manage this EPV and adjust its variable values.. or report. such as the code within a server script service component.Adding an exposed process value to a report When you create an exposed process value (EPV). . You can also reference the EPV from any JavaScript code in a linked BPD.. G.E. you can link it to a BPD. you can link it in a report. 6. and select a business object or click New to create a new custom business object (variable type). Procedure 1.Adding an exposed process value to a BPD When you create an exposed process value (EPV). Click Link EPV and select the EPV from the list. you can link it to a BPD or a service. 3. Results When you run the BPD or service to which the EPV is linked. you can go to the Process Admin Console to manage the exposed process values. Open the BPD or service to which you want to link this EPV. 2. Parent topic:Creating exposed process values (EPVs) Related information: Managing exposed process values (EPVs) 510 . Click the Variables tab. and enable the Backward Compatibility capabilities.Adding an exposed process value to a report When you create an exposed process value (EPV). Before you begin The reporting functionality is deprecated in IBM® BPM V8. in Process Designer go to File > Preferences > IBM BPM > Capabilities. To enable reporting. In the Exposed Process Values section. 2. and open the report to which you want to link this EPV. users can adjust variable values directly from a report. 3. Click the plus sign next to the Performance category in the library. Parent topic:Creating exposed process values (EPVs) Related information: Managing exposed process values (EPVs) 511 . Results Now. Procedure 1. you can link it in a report. by default it is not enabled. click Link EPV and select the EPV from the list. Click the Overview tab. Before you begin To perform this task. Open the Process Designer desktop editor. you must be in the IBM® Process Designer desktop editor. 2. 3. if you want to send an email message to end users as soon as an activity is active and can be completed. Use the type-ahead feature to select your variable. Click the activity or event in the BPD diagram and then select the Pre & Post option in the properties. Tip: You can type any existing variable name. the activity in the BPD diagram includes a circular indicator on the left side (pre assignment) or on the right side (post assignment). About this task You can set pre and post assignments for components in a service. click the variable icon to choose a variable that you have declared in the current BPD that will receive the value. In the field on the left. Open a business process definition (BPD) that includes an activity or event that requires a pre assignment or a post assignment. such as a Coach or a Server Script component.Setting variables in pre and post assignments You can set pre and post assignments for variables when you want to assign a value to a variable immediately before or after an activity or event runs. When you set a pre or post assignment for an activity. For example. The task ID is needed so that the email message sent to end users includes information about the task to complete. 5. 6. Procedure 1. Parent topic:Business objects and variables Related information: Accessing variables in Process Designer Creating exposed process values (EPVs) 512 . 4. you do not have to limit yourself to local variables. you can attach a timer event to the activity and use a post assignment to place the task ID into a variable so that it can be passed to the follow-on activity that sends the email message. To add an assignment. type the variable name that will be used as value for the variable in the left field. click the Add assignment icon ( ) in either the Pre Assignments section or the Post Assignments section. In the field on the right. You can achieve this by using a post-assignment. Modeling client-side human services When you model a client-side human service. provide a lightweight alternative to the earlier human services in IBM BPM versions before V8. you must convert the heritage human service into a client-side human service. which requires you to re-create some of the service flow.5. the dashboards.0.Heritage human service to client-side human service conversion To gain the improved performance of a client-side human service and use the new features provided by the client-side human service. For more information. Coaches are composed from user interface controls called coach views. Heritage coaches.Building coaches You can build a coach as the user interface that process participants or case 513 . They are primarily for compatibility with IBM Business Process Manager before version 8. IBM Business Process Manager provides a number of artifacts that you can use to create these user interfaces. The earlier human services are now referred to as heritage human services. cases. human services provide the logic and user interface through which users can view and interact with business processes. heritage coaches.Which artifacts should I use? IBM Business Process Manager has a number of different artifacts that you can use to create or modify a user interface. Users can access dashboards through the Process Portal. or the instance user interfaces that case workers or people who participate in processes use in IBM Process Portal. see Generating portlets for heritage human services exposed as dashboards. see Coaches and Coach views.5. web-based coaches are recommended. . see Client-side human services and Difference between client-side human services and heritage human services. you build the service flow that defines the activities. For information. A dashboard is a stand-alone user interface that users can run at any time. data or process instances. You can create coach views in Process Designer. . introduced with IBM Business Process Manager V8. . see Dashboards in Process Portal. A task completion user interface implements a specific activity within a process instance. Human services use coaches to build the web pages that users see.5 5. and stock controls. . These artifacts consist of client-side human services. you can also use a coach-based dashboard as a WebSphere® portlet. With heritage human services. It has access to the details of that process instance. used only in heritage human services.5.0 and later. For information. . For processes created with IBM Business Process Manager version 8. Human services provide two types of user interfaces: task completion and dashboards.5. For information about dashboards. Client-side human services. heritage human services.User interface concepts People interact with process applications through user interfaces. coaches.Creating user interfaces for business processes In IBM® Business Process Manager. are composed from a fixed set of user interfaces controls. such as screen size and standard user-interface conventions.Developing reusable coach views To contain functions or user interface elements that another coach view or a coach can use. you can set your coaches and coach views to use the readable versions of Dojo and the Coach framework JavaScript.Coach and coach view examples This documentation includes a number of examples that demonstrate how to create and code the various parts of coaches and coach views. . . which provide the interfaces for end-user interaction. .owners use to interact with a service. you can also specify localized strings for your design-time users. .Coach and coach view troubleshooting The following sections list issues that you might encounter and information about possible solutions. . for example.Localizing process applications Localizing your process applications enables users in different language locales to interact with the application interfaces in their own languages. each of which have their own characteristics.Responsive settings for coach views At run time. . Parent topic:Building process applications 514 . users that are creating their own interfaces using custom coach views that you provide.Tips for debugging coach views in Process Portal You can debug the lifecycle method for your coach views in IBM Process Portal.Tips for debugging coach view lifecycle method inside client-side human services To debug your coach views inside a client-side human service.Building Heritage Coaches When you build heritage human services you can use Heritage Coaches. . you need to use the debugging features of your browser along with the debugging features of the Inspector view in IBM Process Designer. .Enabling JavaScript debugging for coaches For debugging purposes. create a coach view. . users can interact with your application interfaces by using a range of devices. In addition to providing translated versions of your applications for business users. To help you determine which of these artifacts you should use. and stock controls.You want to use some of the features in heritage human services that are not available in client-side human services.You are editing a human service that existed prior to version 8.5. such as collaboration. Heritage human services run on the server but display their user interfaces in a web browser.5. To create or edit heritage human services you use the Process Designer desktop editor.5. . heritage coaches. coaches. see Setting up collaboration features for business users. . Client-side human services are the latest technology in IBM Business Process Manager. Note that a process application can have both heritage human services and 515 .Which artifacts should I use? IBM® Business Process Manager has a number of different artifacts that you can use to create or modify a user interface. If one or more of these conditions apply. heritage human services. there are factors you must consider. Your first decision is whether to use client-side human services or heritage human services. The following diagram summarizes your choices and the text discuss these factors to help you with your choices. Client-side human services are built using the Process Designer web editor and run in a web browser. . The collaboration feature allows multiple users to work on the same coach instance simultaneously.5. Human services in previous versions are now known as heritage human services. These artifacts consist of client-side human services. use heritage human services.You are editing a heritage human service that was created in version 8.You do not need the enhancements and features of the new Process Designer web editor and you prefer to work in the familiar Process Designer desktop editor for your process application development. you should use client-side human services unless one or more of the following conditions apply: . For information. Generally. Generally. Because the stock controls are coach views. you then must decide whether to use coaches or heritage coaches for a particular user interface. you can use these basic user interface elements to create complex coaches and coach views. If you are using client-side human services. A heritage human service can have coaches and heritage coaches in its flow. consider replacing these heritage coaches with coaches to take advantage of the reusability of coach views and the stock controls that IBM BPM provides. Parent topic:Creating user interfaces for business processes Related information: Building heritage coaches Coaches Coach views Controls Client-side human services 516 . you are automatically using coaches and coach views. you need to update a number of similar heritage coaches). Heritage coaches are user interfaces that were created in IBM BPM prior to version 8.client-side human services and both types can use the same coach views. For these user interfaces. If you are using heritage human services. However.0. you should use coaches unless you are updating existing heritage coaches. if the update is extensive in scope (that is. using heritage coaches means that you are updating the user interface using the same artifact that was originally used to create it. Within its own flow. IBM® Business Process Manager provides a number of artifacts that you can use to create these user interfaces. which are reusable UI elements.User interface concepts People interact with process applications through user interfaces. .Coaches Coaches are the user interfaces for human services. The human service can also include gateways and script tasks that affect the flow of the user interfaces or change the variables that are passed into a coach. you can use two types of human services to provide user interfaces that users can use to manage their process and case work in web-based applications such as IBM Process Portal: heritage human services and client-side human services. When you are developing applications in IBM Business Process Manager. A coach is a user interface that users can see in a web browser. Within a process application.Human services In IBM BPM V8. BPD tasks that are implemented as human services contain these user interfaces. A form with multiple text fields and selection controls is an example of a compound view. . Coaches are composed from one or more coach views. 517 . A compound view contains multiple coach views. Authorized users use the dashboard to interact with that information. Coach views can be simple or compound.5.Dashboards A dashboard is a user interface that displays business process information. you create coaches and views by using the Process Designer web editor for client-side human services and the Process Designer desktop editor for heritage human services. A simple view contains a single UI widget such as a text field. .5. Users see and interact with these coaches and views in a web browser when the human service is running. every human service contains at least one coach. The stock controls in IBM Business Process Manager are examples of simple views. advanced items are not coach views or variables. Unlike most of the items on the palette. and behaviors. and buttons. Parent topic:Creating user interfaces for business processes 518 .Heritage artifacts IBM Business Process Manager contains a number of artifacts that are labeled heritage. Coach views can consist of one or more other coach views. data bindings.. . date time pickers. . .Controls Controls are basic user interface artifacts such as text fields.Advanced items for coach views Advanced items are palette items that you can add to a coach view to enhance its content.Coach views Coach views are reusable sets of user interfaces that users use to interact with a business object or service. layout instructions. To learn more about the differences between the two types of human services.5. When you use client-side human services. . server scripts.Human services that are added in IBM BPM V8.Human services In IBM® BPM V8.Heritage human services . With heritage human services. and refined entirely in a web browser. services. and stock controls. such as coaches. and events to create a service flow that is run. and use them to supply user interfaces to web-based applications such as IBM Process Portal. you can use two types of human services to provide user interfaces that users can use to manage their process and case work in web-based applications such as IBM Process Portal: heritage human services and client-side human services. You create and edit client-side human services in the Process Designer web editor. run them on the client-side in the web browser. and events to create a service flow that is run and tested on the server.5.5.The human services in IBM BPM versions that are earlier than version 8. and use them to call the server for data when necessary. see Difference between client-side human services and heritage human services. . . you use coaches. .5. client-side scripts.Client-side human services . The heritage human services are the only type of human services that can call other heritage human services. you use coaches or heritage coaches. heritage coaches. to create user interfaces for business process management. you use existing artifacts.5. Enhanced authoring capabilities such as WYSIWYG (what you see is what you get) and responsive design elements help you build user interfaces for case and process instances and ensure scalability for mobile devices. run them on the server. Parent topic:User interface concepts Related concepts: Heritage human service to client-side human service conversion Related information: Difference between client-side human services and heritage human services 519 .5. services.When you build a heritage human service in the Process Designer desktop editor. you can use web technology to improve human-service performance and provide support for case management and process management. tested.When you build a client-side human service. You create and edit heritage human services in the IBM Process Designer desktop editor. Users can also access the dashboard as a portlet for WebSphere® Portal.Process Performance In addition. a graph in a dashboard shows all the business processes.Team Performance . These standard dashboards include the following dashboards: . ready-to-use dashboards that help you analyze and manage your business processes. they can use the dashboard to interact with the data. Process Portal provides access to many dashboards. It includes several standard. typically it uses charts. A dashboard can also contain other content. Similarly. For example.Dashboards A dashboard is a user interface that displays business process information. A process owner can use the dashboard to identify the problem and then act in a way that enables process instances to finish on time. Although the dashboard can display the data in many different ways. Users can access a dashboard by using IBM® Process Portal. It identifies which processes might need attention because they have process instances that are at risk or overdue. work interfaces. graphs. If users have the appropriate permissions. Authorized users use the dashboard to interact with that information. team leaders can use a dashboard to check the status of work items and reassign work to balance the workload between team members. A business programmer or analyst creates these dashboards by exposing human services and by using the Coaches of those human services as the user interfaces of the dashboard. and other visualization user interfaces. and user preferences from one URL. users can access the dashboard outside of Process Portal. If an administrator exposes the dashboard as a URL. users can see an overview of the data or filter it to concentrate on a particular aspect. Using dashboards. Parent topic:User interface concepts Related information: Customizing the IBM Business Process Manager dashboards Dashboards in Process Portal 520 . A dashboard displays data from one or more business processes. your Process Portal installation might include company-specific dashboards to help you manage other aspects of business processes. 521 . see Dashboards in Process Portal. The users access it through the Process Portal. To maintain compatibility with earlier coaches. A coach can have multiple exit flows with each one associated with a different boundary event.0. The coach views provide the user interface elements and layout for the coach. Both client-side human services and heritage human services can have coaches. The user interface consists of HTML code that is displayed in a web browser. The coaches toolkit that is included with IBM® BPM contains common user interfaces that are called controls. Users can also access it as a WebSphere® portlet. you use coaches. No heritage coach support is provided with the new client-side human services. When a coach is a dashboard user interface. IBM BPM supports heritage coaches only in the heritage human services. but use coaches for new user interfaces for human services. You can combine these common user interfaces to rapidly develop new coaches. Coaches contain one or more coach views. A heritage coach has the technology and architecture of a coach in versions of IBM BPM before V8. The flow leaves the coach when a boundary event occurs.Coaches Coaches are the user interfaces for human services. At run time. which creates a parent-child relationship between these coach views. see Generating portlets for heritage human services exposed as dashboards. For information. When the flow enters the coach. Coach views are reusable so you can create a library of common user interfaces and behavior. You can continue to use and maintain heritage coaches. it is part of the human service flow. When a coach is a task completion user interface. CSS code to control its visual layout. they are not available with client-side human services. Each coach view can also have a binding to a business object. You can include these controls when you are creating your own coach views. For information about dashboards. and JavaScript to define its behavior. users can run it as a stand-alone user interface at any time. To build either type of user interface for human services. the parent coach view is rendered as a <div></div> tag that contains a nested <div></div> tag for each child coach view. the user sees the user interface that is defined for that coach. There are two types of user interfaces for human services: dashboards and task completion. Each coach view can contain one or more other coach views. Heritage coaches can be used only with heritage human services. Parent topic:User interface concepts Related information: Difference between coaches and heritage coaches Developing reusable coach views Building heritage coaches Coach views Dashboards 522 . When you open a coach view definition to edit it. which contains items that you can add to the coach view. and how the coach view is used. you can see the following pages: . For example. If you create a second coach that needs address fields. You can also tag your coach view to make it easier to find in the library and on the palette. Instead.The Behavior page displays the scripts and CSS files used by the coach view. . the changes apply to all instances of the coach view in all applications that use that toolkit. you can reuse the coach view from the first coach. These items consist of coach views. You cannot directly edit the definition of the coach view from within the parent coach or coach view. the images used to represent the coach view during design time. coach views and coaches can share parts of their user interface with other coach views and coaches. . You can edit the properties of each instance independently. advanced items. you can see the change reflected in the instances of the coach view. In general. configuration options (which includes Ajax services). changing the label of one coach view instance does not change the label of the other. be careful in your changes. The layout page also displays the palette. The Behavior page is also where you define event handler code. you must open the coach view definition first before you can change it. the changes apply to the instances of the coach view in the process application. Choosing the process application means that you can reuse it only within the process application. the event handlers contain the functions that the IBM® Business Process Manager framework calls. create highly reusable coach views in toolkits and more specialized coach views in process applications. Because coach views are reusable. deleting a content box in the coach view definition could mean that coaches or coach views that contain instances of that coach view cannot display the content that they had defined in that content box. Coach views can consist of one or more other coach views. it also means that if someone edits the coach view. The event handlers are the entry points for the code of the coach view. data bindings. This approach means that if the coach view definition changes.The Variables page displays the business data binding. and variables. Both instances of the coach view use a reference to point to the coach view definition. If the coach view is in a toolkit and then someone edits it. . and behaviors. In both cases.The Overview page displays the coach view name. However. When you select coach view or 523 . information about the coach view. While the coach view might reference supporting JavaScript files. the coach is using an instance of the coach view. You can create a coach view in the process application or in a toolkit. For example.Coach views Coach views are reusable sets of user interfaces that users use to interact with a business object or service. The page also contains inline JavaScript and style code. layout instructions. and localization resources available to the coach view or used by the coach view. you create a coach that has a coach view that contains a set of address fields. Because editing a coach definition can affect many instances. For example.The Layout page displays the coach views and controls contained within the coach view and their relative positions. You can add your own code to these event handlers in the Behavior page of the coach view. These properties are on a number of pages: General. you see its properties. Visibility. Positioning.Framework managed versus view managed content for coaches At run time. . .control in the layout. IBM BPM treats the stock controls and the custom coach views that you create identically. or by the view.Boundary events A boundary event acts as a trigger within a human service that sends information from a client to a server where the information is then committed and the human service moves to the next step. In terms of use. . Controls are coach views. . . You cannot use JavaScript dot notation. To access binding data and configuration options you must use the JavaScript get and set functions. Parent topic:User interface concepts Related information: Event handlers Controls 524 . you can choose that the content be managed by the view. Configuration. .Event handlers overview Coach views have predefined event handlers that perform callback functions when an event is detected. . the content inside a content box of a coach can be managed by the runtime framework.Data binding for coach views Binding a coach view to a business object creates an association between data and a user interface for it. The view context provides access to this data. but if you want to code your own custom behavior. By default.Templates Templates are an ideal way to create a standardized look across multiple coach views.Coach view properties Each coach view has a set of standard properties. the framework manages the content. and HTML Attributes. IBM BPM provides a set of stock controls on the palette.Binding data and configuration options A coach view may be associated with a data binding and configuration options. you create a coach view that has the company logo and name in a banner area and a content box as a placeholder for other content. if you have a template that has a common banner. For example. if you change the template. When you use this coach view as a template. For example. you can drop it onto a coach so that the coach has the common banner. The new coach views have the content of the template as base content to which the users can then add content. you update the template to change the logo image. Parent topic:Coach views Related information: Example: creating a template Coach views 525 .Templates Templates are an ideal way to create a standardized look across multiple coach views. To continue the previous example. Other users can also use the template when they are creating coach views so that there is a consistent look across the new coach views. you can then select it when you are creating another coach view. Because the template is a reference to a coach view and not a copy. Because templates are coach views. A template is a coach view that someone marks as being usable as a template in its Overview page. all of the coach views based on that template are updated as well with those changes. All of the coach views that use your template are updated with the new logo. you can also drop them onto coaches. The template also serves as a way to update multiple coach views simultaneously. Users can then select the template when they are creating coach views. The new coach view has the banner area defined in the template along with an area for content. for example in millimeters. and HTML Attributes. the Properties area displays several properties pages. Stock controls have examples of configuration properties. Positioning. . Visibility. .Coach view properties Each coach view has a set of standard properties. or relative. These pages contain the properties of that coach view instance.Configuration properties and configuration options You define the configuration options in your coach view so that users can customize a specific instance of that coach view.Coach view visibility properties The Visibility properties page is where you set how the parent coach or coach view displays the coach view instance. for example as a percentage of the available display space. Users see these configuration options as configuration properties in that instance. The General. . and HTML Attributes pages display properties that all coach view instances have. .HTML attributes The HTML Attributes page is where you override styles for a specific coach view instance. When you select a coach view in a layout. These properties are on a number of pages: General. . Configuration.Positioning options for coach view instances You can control the spacing of the coach views in your coaches by setting the positioning properties for each coach view instance. Positioning. Parent topic:Coach views Related information: Developing reusable coach views 526 .Coach view general properties The general properties of a coach view set general text information such as the instance label and binding information such as the data binding and view definition binding. The values that you set can be absolute. The Configuration page has properties that are defined in the coach view definition and they are specific to coach views that are bound to that definition. Visibility. you change the type of the coach view. Sets the business object or data type that is associated with this coach view instance Sets the coach view definition that the coach view instance uses. Provides an area in which you can provide hover help for the coach view instance Provides an identifier that you can use in JavaScript to access this particular coach view instance. Sets whether users can see the label at run time. If you use a variable to set the visibility. The location of the label depends on the coach view type and whether that location has been overridden by CSS coding. The values are Show (default) and Hide. The Control ID is also known as the view ID in the API documentation. the variable must be a string with one of the following values: SHOWHIDE. 527 . and the configuration properties that you previously set no longer apply. The general properties consist of the following fields: General property Label Help Control ID Binding View Label Visibility Description Sets the display name of the coach view. When you change this property. dynamically change the visibility according to various conditions. You can use a variable to. for example.Coach view general properties The general properties of a coach view set general text information such as the instance label and binding information such as the data binding and view definition binding. you might want to have a Text Area control display a large description with no accompanying label. For example. The default value is the name of the coach view. When you set the text direction to Left to Right or Right to Left. the text is locked to the specified direction. a special category of variables. Help. a Text control has an Arabic label. you cannot edit their values in the Variables page. Visibility. For information. Unlike the other configuration options. such as label text. the first strong directional character in a string determines its text direction. This rule applies to all text elements that a coach view displays. called general options. the text in the label is from right to left although the text in the field is from left to right. The default value is Default. These variables contain the metadata for the coach view and correspond to the Label. but its field contents are English. becomes available in the configuration options. Visibility. These stock controls also use them to support click-to-edit functionality. and Label Visibility general properties. For information about setting the text direction. see Adding bidirectional language support. and Label Visibility general properties. Parent topic:Coach view properties Related information: Developing reusable coach views 528 . The Base Text Direction property is available only if you enable the Base Text Direction preference. Note: If you assign a variable for the Label.Base Text Direction Sets the direction of the text that is displayed by the coach view. For example. The Tabs and Table stock controls use the Visibility and Label Visibility properties of the coach views that they contain to handle hiding labels. see Setting preferences in Process Portal. In this case. When you set the text direction to Contextual. text values. Help. and other text that the user sees. which means the coach view uses the text direction that is set in the user's profile. If you do not provide a label. the control is a check box for the Boolean type or text field for a String type. the Radio Buttons stock control has the layout configuration option and a Layout label. they see all the configuration properties that have the same group name. When you define a configuration option for your coach view. you add config1 and config2 to the Config group. When users expand the twistie. . If the type is a simple type. You can choose Horizontal or Vertical for this configuration property. The data type of the configuration option affects how the coach view instance displays the corresponding configuration property. provide the display name of the configuration property. the coach view instance uses the name of the configuration option as the display name. The coach view instance displays the group name with a twistie. One of these configuration properties is Layout. you set the appearance of the corresponding configuration property and the information that it displays. provide hover help text to help users decide on the setting for that configuration property. they see config1 and config2. Users see these configuration options as configuration properties in that instance.Configuration properties and configuration options You define the configuration options in your coach view so that users can customize a specific instance of that coach view. For example. If users expand the twistie. like String. This choice affects only this Radio Buttons instance.In the Label field. the configuration property 529 .In the Documentation field. the Properties area displays a list of configuration properties. For example. the corresponding configuration property is an appropriate control. When users click an instance of the coach view. or is based on a simple type. If the type is a business object.To group several related configuration options. they see the Config group. . For example. . When you drop a Radio Buttons instance onto a coach view layout and then select the instance. provide a group name. the configuration property is a two-column table. If the type is a list of business objects. Here is config4 presented as a configuration property: If the type is a list. Each row in the table represents an item in the list. Each parameter in the business object has 530 . the configuration property is a table with a header row and a row for each list item. Here is config5 presented as a configuration property formatted as a table.is a group that contains the business object parameters as configuration properties. allowing instances of the coach view can have up to three different settings for that configuration property.a corresponding column in the table. This means that Process Designer displays Boolean-typed configuration options set to false by default. Here is config6 presented as a configuration table formatted as a three-column table: A coach view instance uses implicit default values for configuration properties if users do not set a value for them. you must account for its implicit default value. radio button. When you are defining a Boolean-typed configuration option. which is false. such as check boxes being not selected. For example. The implicit default value depends on the type. You can set a configuration option to be responsive to screen size settings. To make a configuration option responsive. or slider control. that corresponding column subdivides into columns for each parameter in the child business object. click Responds to screen size. if your coach view has a configuration property that controls the rendering of a selection control as either a checkbox. each corresponding to a different screen size setting. users can configure their coach view instances to have three different renderings for that control in different user environments. Here are the four corresponding configuration properties: 531 . If a parameter is also a business object. you can select to have the designer create a configuration option of the correct type and bind the configuration property to this configuration option.When users are configuring the coach view instance and want to set a different value for each screen size. they can accept values for different screen size settings provided that those values are web files. When you are setting (binding to data) a configuration property on a coach view instance. Instead. assign a variable to the configuration property by clicking . type or choose a value for the configuration property. However. . medium. One exception to this restriction is configuration options that have a URL type. you can select to display only these variables. Parent topic:Coach view properties Related information: Coach view general properties Developing reusable coach views Data binding for coach views 532 . You can then select an existing variable from the presented list. To bind it statically. The variables with a data type that matches the type that is defined for the configuration options are in bold.You cannot statically bind to a business object that contains nested lists. the designer displays a warning. Then they can change the screen size setting to a new size. or small screen size. Responsive settings are not supported for service-type configuration options. Restrictions: .Only configuration options that are object type can be marked as responsive. By default. If these configuration options are set to be responsive. If you select a variable and its type does not match the type that is defined for the configuration option. the list displays all variables. . Instead of selecting a variable.If a dynamic value is set for a responsive configuration option instance. you must bind to it dynamically. only one value can be chosen. For example. they click the screen size icon next to the configuration option to specify that the value applies to a large. you cannot bind a different variable for each screen size setting. For information about responsive settings for coach view instances see Responsive settings for coach views. you can bind it statically or dynamically. and enter a new value for the configuration option. To bind it dynamically. that the editor highlights the wrapper div when the coach view is selected. You can also specify the height of a coach view. Margin refers to the space outside the coach view border. bottom. and that you apply positioning settings to the internal div. for example. then the margin on all four sides of the view will be set to 15 pt. If a single value is specified for margin or padding. making it difficult to see any styling that is set on the wrapper div. This means. and the width from the left to right border. you can see the border by selecting the coach view so that the border is highlighted. Padding refers to the space inside the border of the coach view. and left of the view. The values that you set can be absolute. for example as a percentage of the available display space. it is recommended that you use a div inside the wrapper div. if the screen space on the run time device is reduced. measured from the bottom to the top border.Positioning options for coach view instances You can control the spacing of the coach views in your coaches by setting the positioning properties for each coach view instance. for example in millimeters. This is because the wrapper is owned by the framework both at design time and run time. To set the values individually for the different sides of the view. For example. Tip: If you are creating a custom coach view and you want to include a border in your coach view. it is applied to all four sides. 533 . you can type them out individually using the format toprightbottomleft or you can click the button next to the field to use the dialog to enter values for each side. The minimum height and width settings allow you to limit the reduction in height or width. corresponding to values for the top. if you specify the view margin with a single value of 15pt. or relative. right. The values that you set determine the amount of space that surrounds the view content. An example of how these settings interact is described below. The margin and padding properties take up to four values. for example. If your view does not have a visible border defined. For example.The values that you specify can be relative or absolute values. all view content is shown in the display area. you can see the inherited values by default. Table 3. Scroll bars always appear with the coach view. in some cases. depending on the unit of measurement that you specify. for example. Overflow settings At run time. You can optionally configure your coach view to behave differently by setting Overflow Content to any of the values in the following table. Relative units of measure Abbreviation % px em rem Description Percentage of viewport CSS pixels Width of letter 'm' in current font Width of letter 'm' in font of toplevel page element Table 2. The supported units of measure are described in the following tables. You can overwrite these values by entering new values for that screen size setting. Table 1. This is the default setting. the contents of a coach view instance might be larger than the display area defined by the Height and Width settings for the view. 534 . However. the small screen setting. these values are inherited by other screen size. if you set positioning properties for your view using the Large screen size setting. Any overflow content is not visible. unless you overwrite these values. particularly in complex coach views that include other views. Overflow Content Settings Value Show all content (visible) Hide overflow content (hidden) Permanent scroll bars (scroll) Behavior All coach view content is always displayed. view content might overlap. Absolute units of measure Abbreviation in mm cm pt pc Description Inch Millimeter Centimeter Point (1/72 inch) Pica (12 points) Coach view positioning property settings follow the same inheritance patterns as other responsive properties. When looking at the view instance under another screen size setting. By default. Optional scroll bars (auto) Scroll bars are automatically included when content is larger than display area. Parent topic:Coach view properties Related information: Developing reusable coach views Example: creating a coach for tablets and smart phones 535 . for example. For example. if it is visible. In both cases. . the variable must be a string with one of the following values: DEFAULT (the code equivalent of Same as parent) EDITABLEREQUIREDREADONLYNONEHIDDEN. users can see the coach view and add or edit values in it or otherwise interact with it. the parent coach view reserves space in the layout to display the coach view if it becomes visible. implementing a validation service or script for the coach that contains the coach view. the section collapses the space between the upper and lower fields. If the middle field becomes visible. the generated HTML still contains the DOM node for the coach view.Coach view visibility properties The Visibility properties page is where you set how the parent coach or coach view displays the coach view instance. Important: Setting the Visibility property to Required does not validate whether a user enters or sets a value. you have a vertical section with three text fields. which means that the coach view uses the visibility property of the coach or coach view that contains this coach view.If you choose hidden. The hidden or none value is the visibility of the coach view on screen and not whether users can see it in the HTML source. the lower field moves down to make room for the middle field. users can see the coach view but cannot interact with the data in it. . If you set the middle field to Hidden visibility. The default value is Same as parent. Setting visibility properties to respond to user screen size Visibility properties can also be set relative to a particular screen size. If you set the middle field to None visibility. the section displays empty space where the middle field would be if it was visible. . Read-only coach views are visually distinguishable from editable coach views and the functionality for editing their data is disabled or removed. for example. dynamically change the visibility according to various conditions.When you set the Visibility property to Required.When you set the Visibility property to Hidden or None. it is disabled. Field 2 with editable Field 2 with hidden visibility visibility Field 2 with none visibility You can use a variable to. For example. You must provide code that does this checking by. If you use a variable to set the visibility.When you set the Visibility property to Read only. 536 . the coach view is editable and also has a decorator that indicates to users that they must enter or set a value.When you set the Visibility property to Editable. users cannot see the coach view or. . and show a simplified version instead. Next. For information about responsive settings for coach view instances see Responsive settings for coach views. You can configure the visibility settings on the coach view instances to hide the more detailed coach view instance in small screen size environments. change the screen size setting to a new size. and then enter the visibility settings for that screen size. click the screen size icon to specify that the setting applies to a large. select the view. one more detailed and one that is pared down to the barest of information for smaller screen environments. Parent topic:Coach view properties Related information: Developing reusable coach views 537 .you might have two versions of a coach view. or small screen size. and enter new visibility settings for that screen size setting. To specify different visibility settings for each screen size. medium. For example.content { display: inline-block. For example.An HTML class attribute in each coach view instance that you want to specifically style. Add a class to the HTML attributes of the text box instance.myText. If the coach view is a top-level view in a coach. Important: Do not use the following names as CSS class names in your HTML source code because they are reserved names: .ContentBox For example. do the following steps: 1.textLabel { display: inline-block.myText. } .Text .HTML attributes The HTML Attributes page is where you override styles for a specific coach view instance.outputTextLabel.Text . width: 100px. . Overriding a style consists of the following things: . However.CoachView . text boxes have their labels above the text area.Output_Text . you want the label to be to the left of the text area.css file and add that file as an included script or add the CSS rule directly as inline CSS. . 2. Parent topic:Coach view properties Related information: Developing reusable coach views 538 . } 3. click Add Class and then in Class name.A corresponding CSS rule for that class attribute. define the myText class to override the styles for the label position: . add the CSS rule to a . In any parent coach view. add a custom HTML item that contains the style rule. Default label position Overridden to move the label To move the label. In CSS code. type myText. define the style for the class. To display one or more parameters of that business object. When the view definition for the coach view declares a binding type. If the variable is a list. you can see that coach view. you create a coach view. the layout displays that coach view. These parameters are available as variables on the palette. Process Designer adds the coach view that is associated with the data type of the variable. a coach view can have only one binding. When the view definition does not declare a binding type. the Address business object can have an associated coach view that displays all the address information.If you drop a currentItem variable onto the layout. Each column contains the coach view that is associated with the data type of the variable. what you drop onto the layout determines the coach view that Process Designer adds to the layout. When a business object is associated with a coach view. you can drop the parameters of the business object onto the layout. the contents in the content box repeats for each list item. .If you drop a listSelected variable onto the layout. Process Designer adds a vertical section that contains the coach view that is associated with data type of variable. When you have a coach view definition that contains a Content Box item and an instance of that coach view is bound to a list. At run time. . If there is a coach view that is associated with that data type of the variable.Data binding for coach views Binding a coach view to a business object creates an association between data and a user interface for it.listSelected. the coach view contains the data for the selected item in the list. At run time. For example.myItem. The Output Text control displays the third myItem string. . Process Designer adds a Select stock control. you can see a Text stock control that is bound to the string. if you drop a string onto the layout. you can see a placeholder message. . At run time. Although a business object can have an association with many coach views. such as a string or one parameter business object. the contents of the section repeat for each item in the list.If the variable is a primitive data type. you have an Address business object.If the variable is a business object with more than one parameter. the data binding is optional. the user selects the third item in the Select control. you must bind the coach view to data. The content box can contain coach views that are also bound to 539 . The Address business object now has an associated coach view. you bind the coach view to the business object. For example. To associate a business object and a coach view. Process Designer adds a Table stock control with a column for each parameter. If the variable is a business object that has an associated coach view. You then add the Address business object as a variable to that coach view. the coach view might not function properly. If the business object does not have an associated coach view. For example. You can change the coach view that the designer selected. It can also have and association with a different coach view that displays just the postal code. For example. Without the data that is provided by the binding. you have a Select control that is bound to listBO[] and an Output Text control that is bound to listBO. The coach views that are bound to innerList. If the outer list has more items. if you bind an inner coach view to the currentItem of a different list. the field contains the first name. If the two lists do not have the same number of items. The list of the contained (inner) coach view provides the contents. the two lists must contain the same number of items. the users see some highlighted coach views in the repeated content. outerList[] has three items and innerList[] has two items. you have a section that is bound to a list of names. They are highlighted because they do not have data. For example. the section repeats for each name in the list. The field in the second section contains the second name. When you have this arrangement. the list of the container (outer) coach view controls the repetition. For example. The user cannot see the coach views for the fifth innerList[] item. but only the first two have data. Parent topic:Coach views Related information: Coach views Business objects and variables in Process Designer Binding data and configuration options Framework managed versus view managed content for coaches 540 . and so on. For example. In the first section. Each repeating section contains a field. the user cannot see these excess items because the inner list has nowhere to display them. The content box for the section contains a Text stock control that is bound to the currentItem of the list of names. At run time. outerList[] has four items and innerList[] has five items.currentitem repeat four times. The specific message depends on whether the inner list contains more or fewer items. You can bind the outer coach view and the inner coach views to different lists. The coach views that are bound to innerList. If the outer list has fewer items during run time.lists or elements of lists. However.currentItem repeat three times. users see a message. the coach view needs to call bindAll() multiples time for each object level.Important: The bindAll() function only handles one level deep in the object tree. phoneBook. For complex data types such as business objects. context.title are notified. the change function is not called. To access binding data and configuration options you must use the JavaScript get and set functions. The view context provides access to this data.binding The binding object.phoneBook. The following sections discuss the different data types and outline the cases where additional code is required for the view to receive notification of a data change.binding. one of which is title. For example. if a view is bound to local. provides access to data that is bound to a view. assume that the view is bound to a complex object local. It is important to note that these notifications will be sent to the view only if the binding object itself changes.phoneBook. You cannot use JavaScript dot notation. For example. The change function is only called if the entire phoneBook object is changed. so if the object has multiple levels (nested objects).title. when a view is bound to the simple string type local. but not if any of its properties or sub-properties change. The view framework detects data changes in the bound object. if defined. You can access data that is bound to a view by using the construct: this. and automatically notifies the view by calling its change event handler function. There is at most one data binding declared for each view. you must manually bind the view to the property by using the bind() or bindAll() function. not the title property. the view's change() function is called with a change event that specifies that the title changed and its new value. but not if any of its properties or sub-properties change.binding){ var title = this.get("value"). All the views that are bound to local.Binding data and configuration options A coach view may be associated with a data binding and configuration options. For example.context. not a simple type like a String. the view framework detects data changes and automatically notifies the view of the change. 541 .title.context. phoneBook.get("value") } The main reason for views to bind to data is so that the view can be notified if the bound data has been modified. where value is a special property name that returns the data binding. If there is a change to the title property.context. because the view is bound to the phoneBook object. Binding to simple and complex data types For simple data types such as strings and numbers. the view is notified only if the binding object itself changes. If you need a view to know if a property of a complex object has changed. then the view can get the phone book's title as follows: if (!! this.binding. Note that you can use the bind() and bindAll() functions in the same way for configuration options. The object phoneBook has several properties. this. .. The following example shows code that you might add to a view's load event handler to manually bind properties of a complex object: var binding = this.person[]. removed.myBindAllChangeHandler. the view is bound to a complex object and sets a change handler to be notified if binding.. see the change event handler topic. . removed. [scope]) . for example using the server script syntax tw. the view's listUpdated function is called whenever a list element is added. consider that the view is bound to the list local. you must manually bind the view using the bindAll() function.bindAllHandle = binding.listOf. Returns a handle to the callback.property2 (which is a string) changes. this).get("value"). Scope is an optional parameter that specifies the context scope of the callback. the framework automatically notifies the view of the change. It also sets another change handler to be notified if any sub-property of property3 changes..bind(path.bindAll(this.property2". For the callback signature. or replaced. For example.bindAll(this.phoneBook. In both cases the scope in which the change handler is called is the view's this scope.property1. If a new person list is created and set to the view's binding.property3Handle = binding. Binding to list updates To be notified when an element is added. this). function(e) {some code}.Notifies the view via callback if a specified property has changed.listUpdated.phoneBook.. The special properties are described in the following table. or replaced. the view is automatically notified when the entire List object changes.. In the example. this.Table 1. //this is a complex object this.binding. Returns a handle to the callback..property2Handle = binding.bindAll(callback.context. Special properties of a list Property Type Description 542 . callback.get("value"). //this is a List object this. In the following code example.person = new tw.local.}. Binding to list properties In addition to the elements of a list. Binding to a list type When you bind to a list. [scope]) .binding.var binding = this. such as a property that defines the list elements that are selected by a user.object.mybindAllChangeHandler(event) { .bind("property1..get("property3"). a list also has special properties. this)..person().context...Notifies the view via callback if any property on the object has changed. Scope is an optional parameter that specifies the context scope of the callback. context. //this is a list this. The selected element. Use listAllSelected to subscribe to a change to this property.selectedIndicesHandle = binding. When you set listAllSelectedIndices. To receive notification of a change in a special property. In general. This value corresponds to the value of the index 0 element of the listAllSelected array. you can subscribe to the individual property using the bind() function. it is not necessary to subscribe to all of the special properties).binding. This property is read-only.var binding = this. it is sufficient to subscribe to one special property (that is. For example: list = this.Use get("value") to get the list object. The bindAll() function does not include these special properties. you pass in the indexes in an array.indicesChanged. Use the following notation to get data from a list: . The index of the selected element.listAllSelectedIndices Array listAllSelected Array listSelectedIndex Integer listSelected Object The indexes of the list elements that are selected by a user. this). The following example code could be added to a load event handler to call a view's indicesChanged function whenever the value of listAllSelectedIndices changes.get("value"). This property is read-only. There can be more than one selected index.get("value") 543 . An array of all the elements that a user has selected. Accessing list elements Lists are a collection of simple types or complex objects with properties. Use listSelected to subscribe to a change to this property. This value corresponds to the value of the index 0 element of the listAllSelectedIndices array.context. Use listAllSelectedIndices when updating the list selection.binding.bind("listAllSelectedIndices". this. This property is read-only. Use listSelectedIndex to subscribe to a change to this property. .get("listSelected") to obtain the value of the listSelected property.get(index | property).binding. . . List operations The following APIs are used to modify a list and to get information about a list.context. this.bind("listAllSelectedIndices". see Accessing list elements.bindAll(this.binding object by calling bind and bindAll again.set("listAllSelectedIndices . Each bind or bindAll function returns a handle which can be used to clean up the binding.Use get(property) to obtain the value of the property. use list. A view can have multiple configuration options. } Configuration options In addition to data.binding. 2.To programmatically update the selected property in the list.items. this.remove(0) To replace an object. use list. use list.Use get(index) to obtain the indexed element.put(index. views also can be bound to configuration options.context.get("value"). this.context.selectedIndicesHandle was initialized in the load function this.put(0.remove(index). For more information.selectedIndicesHandle was initialized in the load function this.get("value"). For example. item) To get the length of a list.set(property). For example.unbind().length(). Use similar syntax to obtain the values of all other properties. . and rebind to the context.binding. this.bindAllHandle.add(item). you can release the bound resources.bindAllHandle = binding. use list.indicesChanged.selectedIndicesHandle = binding. this. this. For example.context. 3]).selectedIndicesHandle.. To get an indexed element or property of the list. // assumes that this.binding. [1.context.add(item) To remove an object.get("value"). The data returned by items should not be modified.options object.Use items to get an array that represents the underlying elements of the list.get(0) to obtain the first element.binding. For example.type != "config"){ var binding = this. item).get("value").context.To add an object.listUpdated. this). a view needs to unbind the manual binding. When a binding data change occurs. or each time the whole binding object is changed. list. For example. - this. For example: list. For example. You should release the bound resources either in the unload() event handler. The values for the configuration can be retrieved using the view's this. use list. For example. the label of a button control is a configuration property. For example: list. this).options contains a 544 . //this is a list // assumes that this. Cleaning up bound resources When a binding is no longer needed. add the following code in the change event handler:if (event. The object context. use list.unbind(). Predefined configuration options of a view Option label Type String visibility String labelVisibility String helpText String Description The label value of the view. which means that Coach Views contained within that table use the visibility settings of the table. The Coach Views are then EDITABLE until the user clicks anywhere outside of the cell. You must provide code that does this checking by. The Coach Views revert to being READONLY. See The coach view context object. Important: Setting the visibility to REQUIRED does not validate whether a user has entered or set a value. implementing a validation service for the Coach that contains the Coach View.Important: Tables have a Disable click-toedit configuration property. the Coach Views in a given cell are READONLY until the user clicks in the cell. When Disable click-to-edit is true. The default value is false. for example. these Coach Views use their own visibility settings. DEFAULT is the code equivalent to Same as parent that users see on screen in a Visibility list. if one exists The visibility settings for the view.Table 2. Valid values are: "DEFAULT" | "EDITABLE" | "REQUIRED" | "READONLY" | "NONE" | "HIDDEN". That is. The visibility settings for the label. Valid values are "SHOW" | "HIDE" The view can use this property as hover text 545 .predefined metadata property in addition to user-defined properties that are configurable for a view. To set a user defined configuration option. use this. use this.options.set("value".options.context. newValue). where myOption is the option name.context.*.To get a view's predefined options.To get a user defined configuration option. .set("value".. to set a view's visibility option.context.options.options.options. These name-value pairs are inserted into the view's DOM attribute Configuration options are accessed and updated in the same way as binding data. where myOption is the option name. use this. use this.myOption. Normally a view does not need to use this as the CSS class names are inserted into the view's DOM attribute A name-value pair map that represents the HTML attribute specified.. For example: . Parent topic:Coach views Related information: change event handler collaboration event handler unload event handler load event handler 546 .To set a view's predefined options. For example.visibility.context._metadata.*._metadata. newValue). use this. .className String htmlOverrides Map The CSS class name(s) specified.context. For example.get("value").context.visibility._metadata. .myOption. use this. to get a view's visibility option.options.get("value")._metadata. Parent topic:Coach views Related information: Building a heritage human service The coach view context object 547 . however. Important: When a boundary event has been specified in a coach. You must add JavaScript code to trigger the event at the appropriate time using the this. the boundary event must be wired to the next state.context.trigger(callback) application programming interface (API). you specify a boundary event on the Overview tab under Usage. This code is part of the behavior defined in the Behavior tab of the view. When you create a coach view. only one boundary event can be specified per coach view. For loopback scenarios where the data is committed and then the same coach reopens. You can use named boundary events in both stock views and custom views. The stock button control views have boundary events specified by default. only the affected data is reloaded in the coach view instead of the full page.Boundary events A boundary event acts as a trigger within a human service that sends information from a client to a server where the information is then committed and the human service moves to the next step. however. The following table lists the stages in the lifecycle and the event handlers that are called in that stage. each subview's view() is invoked before the composite view's view() . Composite views are coach views that contain other coach views. The view() function typically performs logic to determine what a user sees when the view is rendered. When a composite view enters a stage. When a coach is run.Event handlers overview Coach views have predefined event handlers that perform callback functions when an event is detected. For example. you can show or hide labels depending on the visibility setting. Within a stage. during the load() call. The load() function is only called once. such as defining variables. After initialization is completed. The lifecycle consists of a number of stages with their associated event handlers. You can add your own code to these event handlers in the Behavior page of the coach view. the coach views that it contains have a lifecycle that they follow independently. Similar to the load() function. For composite views. the HTML is generated first and then the load() function is called to perform initialization logic. its subviews enter the same stage. Stage 1 Event Handlers load 2 view 548 Description When the coach is run. the event handlers for the composite view and the event handlers for its subviews are called in a specific order. the view() function is called before the user sees the view. each subview's load() is invoked before the composite view's load(). It uses the clear event to remove the decoration. For example. when multiple people work on the same view at the same time. 549 . the view() function is called. The validate(event) function is called when a boundary event occurs and its Fire Validation property is set to Before. when the user deletes a coach view inside a table row or clicks away from the page. The change() function reacts to changes in binding or configuration data. If the change() function is not implemented. the default collaboration coach view logic.3 change collaboration validation 4 unload All of the functions at this stage of the lifecycle can occur in any order and can occur multiple times. takes effect. The unload() function is only called once. The unload() function is called when the coach view is removed from the coach. and recursively invokes the unload() function on all subviews. The event is an error event or clear event. The collaboration(event) function is called if it is implemented. If collaboration(event) function is not implemented. The parent view's unload() method gets called before the child view's unload() method. The unload() function performs any required cleanup. which is to outline the coach view DOM node. The validate(event) function uses the error event to decorate the coach view to show that it has non-valid data. Parent topic:Coach views Related information: load event handler unload event handler view event handler change event handler collaboration event handler validate() 550 . The following is the typical scenario: 1. the view typically does the following in one of its callback methods. Click the content box on the editor.Performs initialization logic as required.If the content box inherits a data binding that is not an array. click the option The View will manage its own content. There are times when you might want to override the default behavior of the framework when a coach is rendered. For example. The Horizontal Section and Vertical Section stock controls in the Coaches toolkit are examples of coach view that have their content managed by the framework. when a view is bound to data that is an array. Open the coach view. A view is created inside the content box for each index element in the array. you can choose that the content be managed by the view. the framework manages the content. the view does the following in one of the its callback methods. for example add/remove/update/decorate the content of the cloned node. the framework clones the DOM node of the content box n times where n is the number of elements of the data binding array. but if you want to code your own custom behavior. .Framework managed versus view managed content for coaches At run time.If the content box inherits a data binding that is not an array. The option for a view to manage its own content is set as a property on a content box at design time. For more information. or by the view.Invokes the framework method this. for example load() . the framework creates a view for each index element in the array. By default. the view is responsible for handling the content inside the content box. the runtime framework handles the content of a content box as follows: .If the content box inherits a data binding that is an array. 3. . View managed coaches When the view manages its own content.the view deeply clones the DOM node of the content box n times where n is the number of elements of the data binding array.context. and switch to the Layout tab.createView() . 4.If the content box inherits a data binding that is an array. . To set the option: 1. You can write your custom code in a callback method such as load() to manage the content. You might want to create views for a different set of elements. 2. the content inside a content box of a coach can be managed by the runtime framework.Performs initialization logic as required 551 . in which case you can choose the option to let the view manage its own content. the framework creates views for the enclosed contents. Initialize and render the sub-views: . see View managed coaches Framework managed content When the content of the view is managed by the framework. for example load() . In the Properties page. Invoke the framework method this.createView() .context.context.delete the binding object for that row directly or indirectly .Add content (for example add new row in table) . Parent topic:Coach views Related information: Coaches toolkit: Table stock control 552 .context.createView() 2..deleteView() The Table stock control that is in the Coaches toolkit is an example of a coach view that manages its own content.Invokes the framework method this.Invoke the framework method this. Add/delete content dynamically .Create the new binding object and add it to the binding array using DataBinding API .Delete content (for example delete row in table) . if you define a binding for an instance. the configuration properties are optional. you can also expose the configuration property to any coach view or coach in a human service that contains your view. Parent topic:User interface concepts Related information: Configuration properties and configuration options Coach views Stock controls 553 . Exposing the configuration property creates a configuration option in the current view with matching binding. and layout implementation as other coach views. you can provide a specific value or you assign a variable. properties. because they are part of IBM Business Process Manager. You do not have to create the configuration option and bind it. For each control. In each control topic. the controls are read only. the data binding is optional. you can modify instances by using configuration properties and by overriding default styling. for example. As a convenience. IBM® Business Process Manager provides a number of controls. You can use them but you cannot modify their definition. variable definition. and buttons. If you want to override the default value. Like other coach views. However.Controls Controls are basic user interface artifacts such as text fields. For each control instance. A warning displays if the business object type does not match the type of the data binding that is defined for the coach view. it must match the type in the control definition. the business object binding table lists the business object type that is defined for the control. date time pickers. However. which means that they have the same data binding. These controls are implemented as coach views. Parent topic:User interface concepts Related information: Example: creating a template 554 . you can add HTML code to a coach or coach view. . advanced items are not coach views or variables.Content box A content box is a placeholder for content that the parent coach view or coach defines. Unlike most of the items on the palette.Advanced items for coach views Advanced items are palette items that you can add to a coach view to enhance its content.Custom HTML By using a custom HTML item. . it is more difficult to reuse it. Additionally. In the parent coach or coach view. However. You cannot add a content box to a coach. the parent coach has an area for its specific content and the customer information view can remain generic. the elements outside of the content box are the same. you cannot drop anything into a content box.Table 1. therefore. In the credit application coach. updating one instance does not affect the other instance. if the parent view or coach contains two instances of the view. provide a content box in the customer information view. you can reuse the customer information view in other views and coaches. For example. When you open a view or coach that uses the content. the content boxes of the two instances are independent. Because the customer information view is generic. you can add content to the coach view that contains the content box.Content box A content box is a placeholder for content that the parent coach view or coach defines. For example. By providing a content box. You might be limited to reusing it in other credit application views or coaches. Instead. This rule applies whether the instances are in the same parent view or in different parent views. If you put the fields and controls for a credit application user interface into the customer information view. you have a coach view for customer information and you are using this view in a credit application coach. Parent topic:Advanced items for coach views Related information: Framework managed versus view managed content for coaches 555 . you can drop palette items into the content box. place the extra fields and controls that are needed for the credit application into the content box. Content box in a coach view and in a parent coach Coach view Coach that contains the coach view In the coach view itself. the content that you drop is specific to that instance of the view. 556 . and vertical section stock controls.options namespaces. The server updates the variable only when it regenerates the entire HTML page. you can add HTML code to a coach or coach view.local namespace only. If you want text that changes dynamically.businessData or tw. In the code. the variable can refer to the data in the tw. That is. In this case.CoachView .user. a coach has a user business object variable with a name parameter that contains the name of the user. Restriction: If your custom HTML item is within a repeating control such as a table or section. When the server generates the HTML page for the client. However. the variable can refer to the data that is defined in the Variables page of the human service under the local node. However.local. the variable can refer to the data that is defined in the Variables page of the view under the Business Data or Configuration Options 557 . horizontal section. users see the variable name instead of its value.Custom HTML By using a custom HTML item. That is. Important: Do not use the following names as CSS class names in your HTML source code because they are reserved names: . {{tw. By wrapping the HTML code. The custom HTML item inserts the elements inside the <div> tag of the coach or coach view. the code generator cannot determine the index of the variable in the list when it creates the page. you should reduce the size of the HTML segment that you are using within your Coach. wrap the HTML code in a <div> tag. the code generator inserts the custom HTML contents as HTML code when it creates the page. you might see a stack overflow exception. For example. tab. Because the list contents are not set until runtime.</div> For coach views. For coaches.name}}. you wrap the variable in double curly brackets. See Configuring the JVM in the WebSphere Application Server product information. The custom HTML item can contain one or more sets of HTML elements such as <div> and <label> tags.ContentBox The custom HTML item supports the use of JavaScript variables for simple types. do not bind it to a variable that is a property within a list item. ensure that the HTML segments within these blocks are not too large. repeating controls are bound to a list. You can have the coach display the name with the following code in an HTML item:<div>Hello. after the server generates the page. You can add the HTML code directly as text by using a managed file or by using a variable.Note: When building Coaches using custom HTML blocks. the container treats all the HTML code as one entity. Custom HTML blocks are designed for use with small to moderatesized HTML segments. the variable can refer to the data in the tw. Normally. consider using a control such as Output Text that is bound to the variable. If the server cannot resolve the variable. it does not update the HTML if there is a change in the value. If you are using a custom HTML item in a container such as the table. it replaces the variable name with its value. If you provide an HTML segment that is too large. nodes. you add the following code:{{tw. Do not add the script using a custom HTML item. Parent topic:Advanced items for coach views 558 . you bind the view to a address business object with a parameter named street.street}} If you place an instance of that view into a coach. For example.businessData. if the user updates the street parameter.address. add the script using inline scripts on the Behavior page of the view. However. if you want to have a view display the name of a street. In an HTML item. Tip: To insert a script. the user sees the value of the street parameter in the view. the contents in the HTML item do not update until the server regenerates the entire page. the recommended approach is to use the new replacement artifacts to take advantage of their enhancements. See the limitations in the table of heritage artifacts for information. process applications can contain both heritage human services and client-side human services. IBM Business Process Manager uses heritage artifacts to support existing process applications so that there is no need to upgrade them. The heritage artifact remains supported in the current version until IBM identifies it as deprecated or removed. A heritage artifact is a technology that belongs to a previous version of IBM Business Process Manager but remains supported in the current version.0 technology).0.5. The following table lists the heritage artifacts. and heritage human services can contain heritage coaches. the artifacts that replaced them and when the replacement occurred. and limitations that apply with using the heritage artifact.0.0 Limitations Heritage coaches (pre-8.0.Heritage artifacts IBM® Business Process Manager contains a number of artifacts that are labeled heritage.Difference between heritage human services and client-side human services Heritage human services and client-side human services operate with similar concepts.5. However. Heritage artifact Heritage coaches Current artifact Coaches and coach views in version 8.0. Calling another clientside human service or heritage human service from within a client-side human service is not supported.5. While you can develop new applications by using heritage artifacts.0 Heritage human services Client-side human services in version 8. construction and execution differences distinguish the two types of human services.5. 559 . . although a newer version of the artifact using a different technology is available. However.0 technology) cannot be added to clientside human services (8.Important: Heritage artifacts are not necessarily directly compatible with artifacts in later versions. Parent topic:User interface concepts 560 .1 and earlier versions of IBM BPM.5.Difference between coaches and heritage coaches The coaches in IBM Business Process ManagerV8.5.5 are different in construction from the heritage coaches in V7.. you can use web technology to improve human-service performance and provide support for case management and process management.Use client-side human services to build new user interfaces in IBM BPM V8. and use them to supply user interfaces to web-based applications such as IBM Process Portal. However. The following table lists some of the main differences between heritage human services and client-side human services. .Human services that are added in IBM BPM V8. with calls for data to the server only when necessary Case management support Not available Available Collaboration Supported Not supported Coach support Available for both coaches Available for coaches only.Heritage human services .With heritage human services.5. For more information. to create user interfaces for business process management. Summary of main differences between heritage human services and client-side human services Compare Authoring in IBM Process Designer Run in Process Designer Heritage human services Desktop editor On the server Client-side human services Web editor Client-side. see Heritage human service to client-side human service conversion. run them on the client-side in the web browser.Client-side human services . and stock controls. and use them to call the server for data when necessary. When you use client-side human services. You create and edit client-side human services in the Process Designer web editor. run them on the server. construction and execution differences distinguish the two types of human services.Difference between heritage human services and client-side human services Heritage human services and client-side human services operate with similar concepts.5. To be able to edit a heritage human service in the Process Designer web editor. in the web browser.Table 1.5 by using the same artifacts that were used to create them and the technology that you are already familiar with.5 for either case or process management. .5. . consider converting the heritage human service to a client-side human service.5. such as coaches. . case workers and people who participate in processes use the user interfaces that are generated from heritage human services and client-side human services to manage their case and process work in web-based applications such as IBM Process Portal. and heritage coaches Heritage coaches are not supported. heritage coaches. You create and edit heritage human services in the IBM Process Designer desktop editor.Use heritage human services to update and expand human services that were created before IBM® BPM V8. you use existing artifacts. 561 . At run time. Usage of JavaScript Server scripts that use server script syntax Client-side scripts that use standard JavaScript syntax Parent topic:Heritage artifacts Related information: Which artifacts should I use? Heritage human service to client-side human service conversion 562 . The primary difference between coaches and the heritage coaches of previous versions is that coaches consist of one or more coach views. The coach framework and the stock control coach views use Dojo 1. users can call on colleagues to help them complete a coach instance. you can create a coach that has a coach view that contains a set of address fields. If the service flow contains one or more heritage coaches. For example.1 and earlier versions of IBM BPM. That is. You can now implement your own custom controls as coach views and then reuse these custom controls in other coach views and coaches. In IBM BPM. with heritage coaches you must re-create the address fields. . the programming for coach views consists entirely of client-side JavaScript. That is. collaboration is not available. of the stock controls. Coaches and heritage coaches also differ in the following ways: . the control ID is the value of the data-viewid attribute of a <div></div> tag. you can wire each button to a different event. Furthermore.5 are different in construction from the heritage coaches in V7. services use coaches for the user interface. For example.5. only the button stock control can fire a boundary event. the coach view is bound to an Address business object and the individual fields are bound to parameters of that business object.8. . . which is available to all of the coach views. For example.6. If you create a second coach that needs address fields.Instead of the one-button mechanism of heritage coaches.Coaches introduce a client-side model to coaches to apply the Web 2.Difference between coaches and heritage coaches The coaches in IBM® Business Process ManagerV8. Any coach view can declare and fire a boundary event. A human service flow can use coaches only. By using the data-viewid attribute. In coaches. There is no need for server-side JavaScript. Programmers use boundary events for actions such as data updates with the server and flows to other coaches or services. More than one person can work on the same coach instance at the same time in their own browsers. This is not the case in coaches because coach views are reusable and you can have multiple views in a coach. This reusability means that you can share common pieces of user interface between coaches. a coach can have multiple buttons. These users see which controls their colleagues are editing and the values that they are setting in those controls. coach view developers can locate the nested view because data-viewid is unique within its parent or enclosing view. coach views use named boundary events.0 appearance and behavior. The control ID of a heritage coach is the div node ID. You are not limited to using only buttons to do so although. Coach views are reusable collections of user interfaces that are frequently bound to a data type. Conversely. fields in different coach views that are bound to the same data object update without requiring a full-page refresh. The coach has data on the client. you can reuse the coach view.Coaches support collaboration while heritage coaches do not. In the human service diagram. heritage coaches are not supported by the web-based human 563 .5. with collaboration.The control ID of a coach is different from the control ID of a heritage coach. Collaboration is available only if the service flow uses coaches for its user interface. However.5.5. and heritage coaches cannot contain coach views. However.The properties area for coach views has different pages from the properties area for heritage coach controls and sections. Visually.5. the implementation of those properties can be different. but not a mix of the two. and Control Id. You can use the filter to show or hide the categories of coach views. a coach cannot contain heritage coach elements. Even when heritage coach controls and coach views have properties that have the same name. . Coach Heritage Coach When you open or edit a coach. That is.The palette uses tags to categorize the coach views that are available. you can see the user interface and palette from V7. coaches resemble heritage coaches in heritage human service diagrams and on the palette. the page that is named after the heritage coach control contains properties such as Label. you can find corresponding properties on the General page. Parent topic:Heritage artifacts Related information: Building heritage coaches Developing reusable coach views Coach views 564 . a user interface for a heritage human service must be a coach or a heritage coach. many of the properties in heritage coach controls have a corresponding property in coach views.The palette contains coach views that you can drop into the coach. Many of the heritage coach presentation properties have a corresponding coach configuration option. When you open a coach to edit it. Although some stock controls and other palette items have the same name in heritage coaches. .services.1. In coach views. Heritage human services that were created in earlier versions can continue to use their existing heritage coaches. When you open or edit a heritage coach. You do not need to migrate your heritage coaches. you can see the user interface and palette for IBM BPMV8. A heritage human service flow can mix coaches and heritage coaches so that one type can flow into the other. For example. Binding. these items are implemented differently. you might notice a number of key differences from the earlier heritage coach: . . To build the client-side human service. The following diagram illustrates the main tasks and activities that are associated with building a client-side human service at a high level. You can then test and run the client-side human service in the web browser. For a suggested order of tasks to build a client-side human service. intermediate events. see Building a client-side human service. you can also map input and output data and set up the exposure type for the service.Modeling client-side human services When you model a client-side human service.Building a client-side human service To create a user interface for a new case instance or process instance. you can implement an activity in your business process definition (BPD) 565 . build coaches. For each activity that is used in the service flow. or the instance user interfaces that case workers or people who participate in processes use in IBM Process Portal. which consists of a series of interconnected steps. use the Process Designer web editor to define the service flow for the client-side human service. About this task To build the service flow. the dashboards. services. create a client-side human service by using the options in the library. Depending on what type of user interface the client-side human service is used for. you can define data variables. client-side scripts. . . you build the service flow that defines the activities. you use coaches.Tools available from the palette for client-side human services Learn about the tools that are available when you are building client-side human services.Implementing an interactive BPD task by using a client-side human service To create an interactive task that participants can perform in a web-based user interface. and end events to model the process or case activities. and create the user interface that users see. you can enable the execution context to be saved. other people can use the client-side human services that you create in IBM Process Designer to create custom dashboards for IBM Process Portal or instance user interfaces for case instances. The postpone event can be used only with client-side human services that implement tasks within a BPD or case type. .by using a client-side human service.Exposing client-side human services In addition to implementing activities in a business process definition (BPD) or a case type. The called service cannot be another client-side human service or a heritage human service. .Validating client-side coaches using client-side validation To ensure that a coach that is in your client-side human service passes valid data in the flow. you can define HTML meta tags in the underlying client-side human service. . . use the Activity wizard.Implementing exclusive gateways in client-side human services An exclusive gateway controls the divergence of a sequence flow by determining the branching of the paths that the flow can take at run time.Declaring variables for client-side human services For each client-side human service that you create. Or they can be exposed as URLs. . you can configure the end event of the service to provide an alternative 566 .Navigation options for after service completion To help the user go to a specific page after the client-side human service completes.Adding HTML meta tags to client-side human services To optimize your HTML pages for being viewed on a mobile device. .Calling another service from a client-side human service You can call a IBM BPM service from within your client-side human service by adding an activity to the service flow. use the coach validation pattern to check its data. you enable a user who starts working on a task that includes multiple steps to close the browser and resume work later without losing work.Saving the state of a client-side human service during execution To allow runtime users to save the state of a partially completed task. By enabling the execution context to be saved. To create a client-side human service for the implementation of your activity.Handling errors in client-side human services To catch errors in client-side human services. depending on a condition. When you add an exclusive gateway to your client-side human service.Enabling work to be postponed and resumed at run time If you want to enable Process Portal users to postpone and resume work at run time. . you can use intermediate events that can be attached to service nodes. . . This activity calls another service that you can specify. you model a point in the execution of the service flow where only one of several paths can be followed. you must declare variables to capture the data that steps or activities in that service flow use. you can add a postpone event to the client-side human service flow. . The HTML meta tags are added to the HTML header when the client-side human service is run. .Validating client-side coaches using server-side validation You can validate coaches in client-side human services using server-side validation. . you use the Inspector in IBM Process Designer to iteratively test and observe how the client-side human service behaves at a detailed level. The Inspector can also be used for problem determination and to identify the source of errors. you can perform many actions by using builtin keyboard accessibility features. Parent topic:Creating user interfaces for business processes 567 .Running and debugging client-side human services When you author a client-side human service. The keyboard accessibility features help you go to and edit client-side human service diagrams in the web editor without using the mouse.Keyboard accessibility for client-side human services In the Process Designer web editor.destination. . The called service adds an activity to the service flow. depending on a condition.Tools available from the palette for client-side human services Learn about the tools that are available when you are building client-side human services. see Building coaches. Use an exclusive gateway to model a point in the flow execution where only one of several paths can be followed. Table 1. For more information. see Calling another service from a client-side human service. the following tools are available from the palette. Use a client-side script when you want to add JavaScript code to run on the web browser in the client-side human service context. Use a service to call another service from within a client-side human service. For more information. and running programmatic commands. see Implementing exclusive gateways in client-side human services. When you are building a client-side human service. The called service cannot be another client-side human service or a heritage human service. for parsing variables. which calls another service that you can specify. . For more information. Tools available from the palette for client-side human services Icon Tool name Coach Client-side script Service Exclusive gateway 568 Description Use a coach to implement the user interfaces that are displayed when you run the client-side human service. For more information about modeling end events in client-side human services. Each path in a service requires its own end event. see Navigation options for after service completion.An end event is automatically included each time you create a service.End event Use an end event to end the service execution. 569 . see Enabling work to be postponed and resumed at run time. For more information. For an example. a postpone event. Error intermediate eventUse an error boundary event to catch errors and receive error data from the service to which it is attached. The default implementation uses the stay-on-page event. The stayon-page event returns the control back to the coach. see Validating client-side coaches using client-side validation. so that any variable updates made since the boundary event for the coach are refreshed on the same user interface page. PostponeUse a postpone event to postpone work on a specified task for later completion. Stay on pageUse a stay-on-page event to loop the service flow back to the previous running coach without drawing a connection to it. you can attach an error boundary event only to a service in the human .Intermediate event 570 Use an intermediate event to add either a stay-onpage event. You can specify the event type in the Implementation tab of the intermediate event. In a client-side human service. or an error boundary event to the service flow. The postpone event halts the execution of the task and keeps the task in a suspended state until it can be resumed at a later moment. This event can be used only with client-side human services that implement tasks within a BPD or case type. Parent topic:Modeling client-side human services Related information: Building coaches Calling another service from a client-side human service Implementing exclusive gateways in client-side human services Navigation options for after service completion Validating client-side coaches using client-side validation Enabling work to be postponed and resumed at run time Handling errors in client-side human services 571 .service in the human service flow. see Handling errors in client-side human services. For more information. In the Coaches tab. click the plus sign next to User Interface and. 7. complete the following steps: Procedure 1. To build the client-side human service.Building a client-side human service To create a user interface for a new case instance or process instance. Open the Process Designer desktop editor. which consists of a series of interconnected steps. you use coaches. 5. To run the client-side human service in the web browser. Open the appropriate process application in the Designer view. click Debug to review the code and make the necessary corrections. If errors occur during the client-side human service execution. In the Variables tab. use the Process Designer web editor to define the service flow for the client-side human service. set the 572 . the coach in the diagram has a button that provides the boundary event that you can use to wire the coach to the end node. Click Save all in the main toolbar to save your work. create a client-side human service by using the options in the library. 6. under New. 4. In the library. You can then test and run the client-side human service in the web browser. add more elements by dragging them from the palette and wiring them together to create the client-side human service flow. which are web-based forms that provide data to users and collect input from those users. In the client-side human service diagram. Iterate through steps 5 to 8 until the client-side human service flows correctly. To create the coaches. click Run . 10. select Client-Side Human Service. 11. Before you begin For some steps in this task. and private variables to support your client-side human service flow. you can add standard fields and controls such as text fields and dropdown menus. output. To expose the client-side human service outside of the business process (for example. 3. The new client-side human service opens in the web editor in the form of a diagram similar to this one. 9. create the user interfaces that are used in the client-side human service flow. in the Process Admin Console or as a page in Process Portal). complete the fields and click Finish. To build the client-side human service. About this task Within the client-side human service flow. 8. you must use the IBM® Process Designer desktop editor. You can use the default button or you can replace it. add input. 2. By default. For more information. and deleting a toolkit dependency in the Designer view 573 .exposure in the Overview page of the service. changing. Parent topic:Modeling client-side human services Related tasks: Creating case user interfaces Related information: Tools available from the palette for client-side human services Declaring variables for a human service Building coaches Creating user interfaces for a BPD Running client-side human services Debugging client-side human services Exposing client-side human services Activating snapshots for use with IBM Process Portal Creating.If you are building the client-side human service in a toolkit instead of in a process application. you can expose the client-side human service as a dashboard in Process Portal. see Exposing client-side human services. Open the BPD in the Diagram view. which you can open by double-clicking the activity in the desktop editor. 5. you must use the IBM® Process Designer desktop editor. add controls and buttons to the coach. 8. The new client-side human service. Complete the Activity wizard. sections. What to do next To run the client-side human service in the web browser. 7. 3. and controls that you can use in a coach. 2. The coach designer is where you customize the coach layout and create or edit the bindings that are between inputs and outputs. the Palette view shows all the elements. complete the following steps: Procedure 1. see Building coaches. Notice that when the coach designer is open. The new client-side human service opens in the web editor in the Diagram view. 4. you initially implement the activity by using the default human service. as required by your client-side human service. click Run Parent topic:Modeling client-side human services 574 . is created and attached to the activity. Click Save all in the main toolbar to save your work. Double-click the activity for which you created the client-side human service. Right-click the activity that you want to work with and select Activity Wizard. . Before you begin For some steps in this task. To implement the activity by using a new client-side human service. Click the Coaches tab and then click the listed coach.Implementing an interactive BPD task by using a client-side human service To create an interactive task that participants can perform in a web-based user interface. To create a client-side human service for the implementation of your activity. 6. About this task When you add an activity to the BPD. which includes a coach by default. use the Activity wizard. For more information about the coach designer. you can implement an activity in your business process definition (BPD) by using a client-side human service. In the coach designer. Open the Process Designer desktop editor. click the plus sign next to Input to add a new input variable. with subsequent words capitalized. If you want to create a new business object. for example: myVar.local. B. 5. Click Select next to Variable Type to select the type of the variable from the Select Library Item list. Variables that represent output data that the current client-side human service returns to its caller.Note: Variable names start with a lowercase letter. 2. What to do next The client-side human service includes variables that can be passed to activities by 575 . Variables that represent input data passed to the current client-side human service. the following JavaScript generates an error when used inside a client-side human service: tw. Variable names are casesensitive. Type a variable name in the Name field. you must declare variables to capture the data that steps or activities in that service flow use.myVariable. complete the following steps: 1. or output variable to the client-side human service. Optional: If you want your variable to be an array. select Is List. 3.Declaring variables for client-side human services For each client-side human service that you create. click New and complete the wizard steps. 4.local. In the Variables tab. input. About this task You can add the following variables to your client-side human service: Table 1. C.pointer= tw. Custom business objects that you created are also listed. D. Procedure To add a private. Iterate through steps 2 to 4 to add output and private variables to the client-side human service. Save the configuration. Open your client-side human service in Process Designer.local.myVariable= {}. Variables available for addition to client-side human services Variable Private Input Output Description Local variables that are used only within the client-side human service. Optional: Type a description of the variable in the Documentation field.Note: Client-side human services do not support business object instances that reference themselves. For example. In the Details section: A. tw.myVariable. Do not use underscores or spaces in variable names. Parent topic:Modeling client-side human services 576 .JavaScript API for client-side human service authoring Use the following reference information to learn more about the client-side JavaScript system variables that are available in IBM Process Designer for clientside human service authoring.mapping input and output variables. . The name of the process or case instance in which this client-side human service is running.processApp tw.system.id tw.processApp. 577 . The acronym of the process application or toolkit that contains the client-side human service.processApp. The name of the process application or toolkit that contains the client-side human service. and returning them back to the client-side human service. Additional system data is available by calling a service that retrieves the system variables that you are interested in.id tw. The process or case instance in which this client-side human service is running.system. The identifier of the process or case instance in which this client-side human service is running. The snapshot of the process application or toolkit that contains the client-side human service.processInstance tw.acronym tw.processApp.id tw.processApp.snapshot. JavaScript system variables available in IBM Process Designer for clientside human service authoring Variable tw.system.system.JavaScript API for client-side human service authoring Use the following reference information to learn more about the client-side JavaScript system variables that are available in IBM Process Designer for clientside human service authoring.processInstance.processInstance.system.system.system. These variables are populated when the client-side human service is run and reflect the state of the system at that point in time.processApp. This variable applies only if the clientside human service is running in a process or case instance. The identifier of the process application or toolkit that contains the client-side human service.snapshot tw. The identifier of the process application or toolkit snapshot that contains the client-side human service.name Description The process application or toolkit that contains the client-side human service. Table 1. This variable applies only if this is a named snapshot.snapshot. The name of the process application or toolkit snapshot that contains the clientside human service.processApp.system.system.name tw.system.name tw. These variables are not meant to be updated within the client-side human service. processInstance. The identifier of the task in the process or case instance in which this client-side human service is running.processInstance.task.process tw. provided as a JavaScript Date object. The task in the process or case instance in which this client-side human service is running.desc ription tw. provided as a JavaScript Date object.processInstance.processInstance.processInstance.narrative tw. The date when this process or case instance started.processInstance.processInstance.processInstance. The descriptive narrative for the task in the process or case instance in which this client-side human service is running.startDate tw. provided as a JavaScript Date object.system.system.processInstance.system.caseFolderId tw.system. The name of the process or case type model for the process or case instance in which this client-side human service is running.atRiskDate tw.subject tw. The identifier of the case folder associated with the case instance in which this client-side human service is running.tw.processInstance.task.id tw.system. The process or case type model for the process or case instance in which this client-side human service is running.process. This variable applies only when the client-side human service is running in a case instance.processInstance.nam e tw. The subject is visible in IBM Process Portal.atRiskD ate tw. The date when this task is due to be completed.task.system.system.system. The date when this task is considered at risk of being overdue.system.dueDate The date when this process or case instance is considered at risk of being overdue.process tw. The description of the process or case type model for the process or case instance in which this client-side human service is running.processInstance. The date when this process or case instance is due to be completed. The narrative is visible in IBM Process Portal.system.process.task tw.task. The process or case type model for the process or case instance in which this client-side human service is running. The descriptive subject for the task in the process or case instance in which this client-side human service is running. 578 . provided as a JavaScript Date object.processInstance. provided as a JavaScript Date object.system.dueDate tw.task.system.processInstance.system.system. 579 .system.task.status The task status specified as a string value. The name of the process application or name toolkit that contains the process or case type in which this client-side human service is running.system. The acronym of the process application acronym or toolkit that contains the process or case type in which this client-side human service is running.processInstance.s The snapshot of the process application napshot or toolkit that contains the process or case type in which this client-side human service is running.system. It can take one of the following values: 50.processApp.system.processInstance.task.system.processInstance.processInstance.tw.system.processInstance. This variable applies only if this is a named snapshot.task.processApp.system. Normal. Highest tw.processInstance.priorityV The task priority specified as an integer alue value. tw.processApp The process application or toolkit that contains the process or case type in which this client-side human service is running. tw. High.s The name of the process application or napshot.task. tw. This is either the previous owner of the task or the user who launched the process or case instance.id or toolkit snapshot that contains the process or case type in which this clientside human service is running. Otherwise. 40.processInstance. 20.owner The user name of the user assigned to this task.system.name toolkit snapshot that contains the process or case type in which this client-side human service is running. if this client-side human service is running in a process or case instance. tw. 30. Low. tw. tw.i The identifier of the process application d or toolkit that contains the process or case type in which this client-side human service is running.system.user The task owner.processInstance. provided e as a JavaScript Date object. the user who initiated the client-side human service. tw.system.processApp.processInstance.processInstance.startDat The date when this task started.system. tw. tw.priority The task priority specified as a string value.task. tw.system.processApp.task.system.s The identifier of the process application napshot.processInstance.processApp.processApp.processInstance. 10 tw.originato The user name of the user who r originated this task. tw. It can take one of the following values: Lowest.system.processInstance. Otherwise. as specified in the user preferences.system.manages An array of teams managed by this user.name The name of a team managed by this user.system.id The identifier of the task owner.coachValidation. Otherwise.tkShortName The toolkit acronym for a team that this user manages.system. tw. if this client-side human service is running in a process or case instance. tw. The value is provided as a string.system.system. tw. tw.fullName The full name of the task owner. tw.user.system.system.user.user.user. Updates to the list must be done through the functions of tw. This variable is used for bidirectional language support.tkShortName The toolkit acronym for a team that this user is a member of. tw.validationErro The list of validation errors for bound rs variables.user.system. tw.locale The user's locale. Otherwise. tw.system.system.id The identifier of a team that this user is a member of.baseTextDirection Controls the text direction. tw.system.coachValidation The validation results for variables that are bound to coach views within a coach of this client-side human service.teams[i].system.manages[i].id The identifier of a team managed by this user.teams[i].user.system. 580 .system.name The name of a team that this user is a member of.user.name The name of the task owner.tw. if this clientside human service is running in a process or case instance.user.system.user.user.user.manages[i]. if this client-side human service is running in a process or case instance.user. the full name of the user who initiated the client-side human service.system.user.manages[i]. tw. the identifier of the user who initiated the client-side human service.teams An array of teams that this user is a member of. tw. tw.coachValidation.user. tw.system. tw.localeDescription A human-readable description of the user's locale.teams[i]. the name of the user who initiated the clientside human service. tw. processInstance. If the list already contains a message for the variableName.The errorMessage is the message used by the coach view to indicate the validation error within the coach.error.starting The identifier of the starting case DocumentId document.system.task. tw. tw.coachValidation.clearValidatio Removes all the validation errors from nErrors() the list.coachValidation. if a validation error exists. if the client-side human service is running as a task in a case instance.error The namespace that provides information about the last caught error.updateValidat Updates the validation error for the ionErrorMessage(variableName. errorMessage) variable to the list of validation errors. Returns true if a validation error was updated.system. tw. tw.coachValidation.system.removeValida Removes the validation error for the tionError(variableName) provided variable name.Returns false if a validation error for the variable name does not exist. Parent topic:Declaring variables for client-side human services 581 .enabling The identifier of the enabling case DocumentId document.system. tw. tw.coachValidation.code The code of the last caught error. variable name that is provided with the errorMessage) new error message.task.system. tw.error. tw.local.addValidation Adds an error message for a bound Error(variableName.tw. tw. the message will be replaced.system. if the client-side human service is running as a task in a case instance.data Data about the last caught error that can be mapped to a local variable. The variableName is the fully qualified variable (for example.variable1).processInstance. Click Save all to save the configuration of the client-side human service. Open the appropriate process application in the Designer view. . you can select this option to update the process or case instance variables with the latest variable values in the client-side human service.Note: If the client-side human service is used as an instance details user interface for a BPD or case type. set the input and output mapping for the servicecalling activity. For more information. in the Implementation tab. The client-side human service opens in the web editor. Decision services. The called service cannot be another client-side human service or a heritage human service. and wire it as required. IBM Case Manager Integration services. In the Diagram view.Calling another service from a client-side human service You can call a IBM® BPM service from within your client-side human service by adding an activity to the service flow. use the Service tool from the palette to add an activity to the service flow. On the Data Mapping tab. In the Process Designer library.Refresh the process or case instance variables: If updates to the process instance variable values are made at run time. you can select this option to refresh the variables with the last saved variable values from the client-side human service.Send the variable updates to the process or case instance: If your clientside human service modifies the values of its input variables at run time. 4. select Map input data automatically if you want the input variables be mapped automatically in the client-side human service. In the Properties view. or clear the check box and go to the Data Mapping tab in the Properties view to enter the data mapping yourself. click Select and specify the service to be called by the selected activity. click User Interface and open the client-side human service that you want to work with. 3. General System services. Click the new activity in the client-side human service diagram to open the activity. Also. Ajax services. 5. This activity calls another service that you can specify. To call another service from a client-side human service. For more information. Parent topic:Modeling client-side human services 582 . see Service components in Process Designer. or Integration services. 6. or build a client-side human service as described in Building a client-side human service. 2. see Creating user interfaces for a BPD or Creating case user interfaces. the Implementation tab provides the following options under Behavior: . complete the following steps: Procedure 1. About this task The services that you can call from the client-side human service include Advanced Integration services. 583 . Ensure that the default sequence flow under Default Flow is the one that you want the flow to follow if all conditions evaluate to false. Click the Implementation tab. you define JavaScript conditions that evaluate to true or false in the implementation properties of the gateway. in the list select the 584 . 2. Wire the gateway in the service flow to create the required sequence flow to and from the gateway. is the first sequence that you create from the gateway to a following activity. see the Sample exclusive gateways section in the Example gateways topic. Click the gateway in the diagram.Implementing exclusive gateways in client-side human services An exclusive gateway controls the divergence of a sequence flow by determining the branching of the paths that the flow can take at run time. If not. complete the following steps: Procedure 1. The default sequence flow is the first sequence flow that you create from the gateway to a following activity. specify a condition (in JavaScript) for each outgoing sequence line to control which path is followed. You can change the default sequence flow at any time. specify a name and provide a description for the gateway. About this task To model an exclusive gateway. the flow follows the default sequence flow. In the General properties. depending on a condition. Open the appropriate client-side human service in the Designer view. To add an exclusive gateway to a client-side human service. as shown in the following example: The default sequence flow. under Common. In the Diagram view. 6. which does not have a condition. Under Decisions. The conditions that you define for the sequence flow lines that emerge from the exclusive gateway determine the path that the flow follows. When you add an exclusive gateway to your client-side human service. For examples of exclusive gateways that are implemented in a client-side human service or a business process definition (BPD). The flow follows the first condition that evaluates to true. which is marked with a forward slash (/) sign on the diagram. If all conditions evaluate to false. 3. you model a point in the execution of the service flow where only one of several paths can be followed. drag the Exclusive gateway tool from the palette onto the diagram. 5. 4. sequence flow that you want to designate as the default sequence flow. If you do not want the sequence line name to be displayed in the diagram. Parent topic:Modeling client-side human services 585 . under Common clear Name Visible. 8. 7. Click Save all in the main toolbar to save the gateway configuration.Note: The default sequence flow does not have a condition. Click a sequence line and verify its implementation on the Flow tab. either on the incoming connection to the called service or on the outgoing connection. you can enable the execution context to be saved. you enable users to save the execution context on the activity or step. In heritage human services. enable users to save the execution context only at key points of the client-side human service. stand-alone services. 2. If the client-side human service calls another service. so that they can complete one page and come back to the next page later: Tip: To avoid network overhead. select a point in the service flow where you want users to be able to save the current progress. To enable users to save the execution context of the client-side human service.The ability to save execution context applies only to client-side human services that are running within business process definitions (BPDs) or case instances. open the client-side human service that you want to model in the Diagram view. When you save the execution context. complete the following steps: Procedure 1. For example. you save the state of the client-side human service while it is being run. and there are steps in the called service for which Save execution context is selected. not at the sequence-flow level. you can choose to allow users to save the execution context between two coaches. In the diagram.Saving the state of a client-side human service during execution To allow runtime users to save the state of a partially completed task. the save settings in the called service are ignored.To incrementally save your progress in a client-side human service that runs as a BPD or case task. as illustrated in the following image. such as an integration service or a general service. you enable a user who starts working on a task that includes multiple steps to close the browser and resume work later without losing work. or URLs cannot be saved. About this task Restriction: . In Process Designer. 586 . The execution context for client-side human services that are exposed as dashboards. you must specify the save settings at the client-side human service level. To ensure that your save settings take effect. specify them in the client-side human service itself. By enabling the execution context to be saved. including the current state of the variables and the position in the service flow. . 3. Parent topic:Modeling client-side human services 587 . 5. 4. On the Implementation tab. ensure that Save execution context for task implementation is selected. Click Save all to save the client-side human service configuration. under Settings. Repeat steps 2 and 3 for each point in the sequence flow where you want runtime users to be able to save the execution context. . see Example: validating data in a coach that is used in a human service.Connect gateway to the stay on page event. 2. About this task To validate data in a coach in a client-side human service without accessing a server to do the validation. Procedure To validate a coach in your client-side human service. For information.Validating client-side coaches using client-side validation To ensure that a coach that is in your client-side human service passes valid data in the flow. use client-side validation to ensure that required fields contain data and before dates precede after dates. Select the flow line and rename it to Yes. use server-side validation. The validation scripts can flow to the same exclusive gateway to 588 . Ensure that this line is the default flow for the decision. In the screen capture. complete the following steps: 1. use client-side validation. Select the line and rename it to No.An exclusive gateway to route the flow according to whether the data is valid . Using client-side validation means that the client-side human service does not need to do a server call to determine whether the coach data is valid. For an example. or any other diagram element. Add the following elements to the diagram to create a validation pattern: . The following screen capture shows the validation pattern. For example.A stay on page event to return the flow back to the coach when the coach data is not valid 3. Make the following connections: .A client-side script to contain the code that performs the validation . . use the coach validation pattern to check its data. If you do need to access a server to validate the coach data. The stay on page event loops the service flow back to the coach. to another gateway. .Connect the boundary event of the coach to the script. This branch of the gateway could connect to another coach. Tip: You can have multiple boundary events with each one leading to a different validation script. the non-default branch connects to an end event. see Validating client-side coaches using server-side validation The typical coach validation pattern consists of a client-side script for coach validation or a called service.Connect gateway to the rest of the human service flow.Connect the script to the exclusive gateway. followed by a validation decision that has a stay on page event that is attached to it. Open the client-side human service that contains the coach to be validated. startDate. in its Implementation properties. If there are errors.").var3[]".local. Select the exclusive gateway and.coachValidation. select the script of the validation pattern. The test checks for the presence of validation errors and.endDate. there is nowhere to display a validation error if one occurs. "The start date must precede the end date. String errorMessage) JavaScript API to identify the coach view that has the problematic data and provide a message that helps the user correct the problem. call the function using code such as:tw. 5.system.local. add a function such as the following example: tw. Save your changes.local. 4. For example.local. Tip: To reuse validation logic. if a coach view is bound to tw. add a script element to the diagram to contain the shared logic. the coach validation pattern loops the flow back to the coach.If the data is valid. which indicates the control with the problematic data and can display the image.addValidationError(String variableName.coachValidation. . and then click Run .If you are validating a list and you want the error to refer to the entire list. you place this as the first element in the flow.validationFn = function validateCutomerAndOrder ( ) { // Shared logic goes here.validationErrors. 589 .If a coach view that is being validated contains rich text.reuse its logic.getTime() > tw. "Var3 has validation error"). routes it to the rest of the flow.coachValidation.startDate".system.If the data element that is being validated is not bound to a coach view.system. add JavaScript code that identifies problematic data.local.coachValidation.local. Use the tw. . the variableName parameter must include [] as a suffix.addValidationError("tw. 6. In the script element.getTime()) tw. In the diagram. Set the start date before the end date. if there are none.local. } In the validation scripts.addValidationError("tw. This matches coach view binding where [] indicates that the object is a list. The test is tw.validationFn(). the flow must go first to the validation script to do the coach data validation: . the flow moves to the next node. test that the coach validation works correctly. In the Script properties.var3[]. 7. Note: .system.length==0. which is a list. the validation script must remove the formatting before validating the contents.If the data in the coach is not valid. you need code like the following example: tw. you can define it once then call that logic multiple times To reuse the validation logic. In the browser. and try again. . Typically. For example:if (tw. At run time. create the test. the flow goes to the stay on page event so that the coach can show the control with the problematic data and a message. Error information is passed to the coach. Parent topic:Modeling client-side human services Related information: Validating client-side coaches using server-side validation Example: validating data in a coach that is used in a human service 590 . The validation must access private or confidential data that should not be made available to the client. Procedure To validate a coach by using server-side validation: 1. the human service flow calls a service on the server to do the validation.You are migrating heritage human services to client-side human services and you want to reuse some or all of the validation scripts you had in the heritage human service. That is. create an input variable that contains the data from the coach B. examine the script logic to move appropriate validation code to the client to minimize server calls. For example. you have Order coach in which users can order parts and you want to validate that a part is in stock. Create the service that validates the coach data. 2.Validating client-side coaches using server-side validation You can validate coaches in client-side human services using server-side validation. However. If you do not need to access a server to validate the coach data. combining them in this way provides better performance. About this task In server-side validation for coaches in client-side human services. see Validating client-side coaches using client-side validation. Open the Process Designer desktop editor. 591 . . The example code uses a general system service called Save Ticket Service. The human service consists of several fields and a Create Ticket button. The service cannot be a human service but it can be any other type. It is not practical to use client-side validation in this situation. The client-side human service then handles any messages that are returned by the server. For information. The following procedure uses a help desk client-side human service as an example. The client-side human services call the validation service that you previously used.The validation must access server-based data or large amounts of data to do the validation. Use server-side validation to validate data in a coach in a client-side human service when the following situations apply: . . a single server-side service validates the ticket and also saves it. Tip: Where possible. combine your server-side validation with server-side logic that does work as shown in the examples in this procedure. While you could do this in separate steps in the human service. It also places related logic together to produce more maintainable models. A. Server-side validation is the more secure approach. you can use clientside validation. Create the validationResults(CoachValidation) private variable to contain any validation messages. In the Variables page. Loading large amounts of data impacts the performance of the client. add the following code to the No branch:tw.ticket. .object. If there is a problem with the coach data.summary == null || tw. Connect the gateway to the error end event.local. In the Implementation properties of the decision. Connect the Start node to the script and connect the script to the decision. tw. In Diagram page.An error end event E.hasValidationErrors = false. D.summary.local.ticket != null) { // If there is nothing in the summary.addCoachValidationError(tw. } } G. add the following elements: . Add JavaScript code to the script to validate the coach data.hasValidationErrors == true H.ticket. such as a nested service that saves the coach data or an end event to complete the service. For example.local.system. add the error to the Coach Validation object if (tw.validationResults. the script must also set isValid to false. tw.").CoachValidation(). For example.local.hasValidationErrors = true. Select the flow line and rename it to Yes.length == 0) { tw. // Set to false unless the data fails a validation test if (tw. "tw.A decision gateway to route the flow according to whether the data is valid . add code like the following example:// Create the CoachValidation object tw. "The problem summary is required. if the help ticket must contain information in the Summary field.local. The resulting diagram looks something like this example: F.A nested service or other elements in the service flow to handle when the data is valid. Connect the gateway to the flow that handles valid data such as a service that saves coach data. Create the hasValidationErrors(Boolean) private variable to indicate when there is data that fails the validation tests.local.local.summary".C.local. . set Error code to coachValidation and set Error mapping to the 592 . In the Implementation properties of the error end event.A server script to validate the data.local.validationResults = new tw. Select the flow line and rename it to No. The script code must create a CoachValidation object that contains an addCoachValidationError instance for every problem with the coach data.ticket. set it to catch specific errors and map the error data to the tw.coachValidation variable. the intermediate event is an error boundary event.validationResults variable. Because it is attached to a service.system. In the Implementation properties of the client-side serves. map the variable that contains the coach data to the appropriate business object. Parent topic:Modeling client-side human services Related information: Validating client-side coaches using client-side validation Handling errors in client-side human services 593 . 7. In Implementation properties of the error boundary event. add a service to your diagram and wire your coach to the service. 6. 4. Add an intermediate event to the service.tw. select to call a service and then select the server-side validation service that you created in step 2. 3. These properties are the mechanism by which the client-side human service receives the validation messages. In your client-side human service. In the Data Mapping properties.local. Connect the error boundary event to a stay on page node. The Process Designer web editor displays the human service. 9. Open your client-side human service. 5. 8. Then. Table 1. you can use intermediate events that can be attached to service nodes. Usage of error events in client-side human services Icon Error event Error boundary event that is attached to a service node in a client-side human service Description Catches errors and receives error data from the service to which it is attached. Open the Process Designer desktop editor. For reference information. and mapping to a variable after the errors are caught. connect each one to the error handling logic that applies. In client-side human services. . consider the following points: . . or you can move it to another service. you can remove it from the service. Procedure To add an error boundary event to a service in a client-side human service: 1. For each error boundary event. Open the client-side human service that you want to work with.error. When you plan to use error events in your client-side human service.The error event information is captured in the tw. events with incompatible data types are filtered out and the data is captured in a local variable. .error.Handling errors in client-side human services To catch errors in client-side human services. see JavaScript API for client-side human service authoring. use different error codes or error data to differentiate between the different kinds of errors. The error boundary event is triggered while the service is running and interrupts its execution.Tip: If you want to have different error handling logic for different errors.Consider specifying the error properties to catch specific errors.You can attach error boundary events only to service nodes in your client-side human service. the intermediate event becomes an error boundary event that catches errors and receives error data from the service to which it is attached. define multiple error boundary events on the single service node. 594 . .By mapping the error boundary event to a variable.You can reposition an error boundary event inside the service. filtering on the error code for the types of errors that are caught.data variables.code and tw. 2. About this task When you attach it to a service node. the error boundary event cannot exist as a stand-alone error event outside of a service node. 5. under Event Properties. in its Implementation tab. In the Diagram view. select Catch all errors or Catch specific errors to specify what type of errors you want the error event to catch. The intermediate event changes into an error boundary event that is attached to the boundary of the service. Parent topic:Modeling client-side human services Related information: Validating client-side coaches using server-side validation Validating client-side coaches using client-side validation 595 . If you selected Catch specific errors. Click Save all to save the configuration.3. For example. and map the error data to a local variable. you can connect it to a coach that displays an error message to a user. 7. 6. click the pickers next to Error code and Error mapping to filter on the error code for the specific errors that can be caught. Connect the error boundary event to the logic you want to run when the error occurs. 4. Select the error boundary event and. drag the Intermediate event tool and drop it onto the service node that you want to attach it to. click the plus sign next to User Interface and create a client-side human service. About this task You can add HTML meta tags such as viewport to a client-side human service at design time. The HTML meta tags are added to the HTML header when the client-side human service is run. the meta tags of the root HTML might take precedence. or click User Interface and select an existing client-side human service. under HTML Meta Tags. select the meta tag that you want to add. the viewport meta tag controls the scaling of the viewing area on mobile devices and enables you to specify a width for your HTML page that would make your content easier to view on that mobile device. complete the following steps: Procedure 1. you can define HTML meta tags in the underlying client-side human service. 4. For example. In the list of available meta tags. To add an HTML meta tag to your client-side human service. select the check box to turn on a meta tag or clear the check box to turn off the meta tag. you override the default settings of the browser and adjust the scaling of the HTML page to the screen resolution of the specified mobile device. Click Save all to save the configuration of the client-side human service. In the Process Designer library. On the Overview tab of the client-side human service. Consult the specifications for the individual tags to understand what behavior to expect in these cases. 2. 3. and enter the corresponding tag content. such as Process Portal.Adding HTML meta tags to client-side human services To optimize your HTML pages for being viewed on a mobile device.Note: These settings apply to the HTML page for the client-side human service. Parent topic:Modeling client-side human services 596 . When the client-side human service is hosted within a larger page. When you add a meta tag to a client-side human service. About this task The postpone event halts the execution of the task and keeps the task in a suspended state until it can be resumed later.Enabling work to be postponed and resumed at run time If you want to enable Process Portal users to postpone and resume work at run time. under Event Type. The default implementation of the intermediate event is a stay-on-page event. when work is postponed on a specified task. When a postpone event is reached. Open the Process Designer desktop editor. The postpone event is only available when you selected Do Not Expose (Service contained in a BPD or case type). In the Implementation tab of the 597 . and add an outgoing connection from the postpone event back to the node where you want work to be resumed later. 6. To enable users to postpone work on a task. Open the client-side human service that you want to work with. 5. which determines what the user will see after the service is postponed. the execution of the service flow resumes at the node specified by the postpone event. Select the intermediate event and. For example. 2.Tip: If the postpone option is not available under Event Type. the service state is saved for later retrieval and the task is returned to the inbox where it can be claimed again. See Exposing client-side human services. You can configure navigation options for the postpone event that indicate the intended behavior upon task postponement and determine what the user sees at run time. When the task is opened later. The postpone event can be used only with client-side human services that implement tasks within a BPD or case type. 4. select the postpone event . complete the following steps: Procedure 1. In the diagram. connect the postpone event to the node where you want the task work to be postponed. check your exposure setting on the Overview tab. in its Implementation tab. Any associated coach is closed. Select a navigation option for the postpone event. the user can be returned to a case details user interface or to an IBM Process Portal page if a URL is specified as a JavaScript expression. 3. In the Diagram view. click the Intermediate event tool on the palette and drag the event onto the diagram. you can add a postpone event to the client-side human service flow. surround any literal values with quotation marks. Navigation options available for postpone events Option Default (behavior provided by the hosting UI) Go to the instance details UI Go to a specified URL Description Go to the default page provided by the hosting user interface. Important: Navigation occurs only if the hosting user interface provides navigation support. Parent topic:Modeling client-side human services 598 . Specifies a relative URL to go to when the service is postponed.postpone event. Click Save all to save the configuration. such as Process Portal. under Event Navigation. 7. Go to the instance details user interface for the case or process instance within which the client-side human service is running. Because the URL is specified as a JavaScript expression. The URL is relative to the hosting user interface such as Process Portal. select one of the following options: Table 1. you can configure the end event of the service to provide an alternative destination. such as Process Portal. under Event Navigation. such as Process Portal. Go to a specified URL Specify a relative URL to go to when the service completes. Go to the instance details UI Complete the client-side human service and go to the instance details user interface for the case or process instance that the client-side human service runs in. In the Implementation tab of the end event. surround literal values with quotation marks. but if the hosting user interface does not provide navigation support. the user can see the case details user interface for a case instance or an IBM Process Portal page if a URL is specified as a JavaScript expression.Navigation options for after service completion To help the user go to a specific page after the client-side human service completes. such as Process Portal. the following navigation options are available. Parent topic:Modeling client-side human services 599 . This option applies only to client-side human services that run in a case or process instance.Table 1. For example. Navigation options available for end events Option Description Default (behavior provided by the hosting Complete the client-side human service UI) and go to the default page that is provided by the hosting user interface. Important: Navigation occurs only if the client-side human service is hosted in a user interface that supports navigation. The client-side human service notifies the hosting user interface of the URL to go to. The URL is relative to the hosting user interface. navigation does not occur. The implementation options for the end event indicate the intended behavior upon completion of the service and determine what the user sees at run time after the client-side human service completes successfully. Because the URL is specified as a JavaScript expression. Troubleshooting errors from running client-side human services Errors that occur when client-side human services run on the client side are logged to the browser console. because it enables you to examine the behavior of each step of the execution flow.Debugging client-side human services If errors occur while the client-side human service is running.Running and debugging client-side human services When you author a client-side human service. When you debug the client-side human service. . The browser console provides the error type. Developers can use the Inspector to demonstrate current service design and implementation in playback sessions. the Inspector enables you to step through each node in the flow to validate that it works as expected.Running client-side human services Authoring a client-side human service is an iterative process that can include several playback sessions. The debugging feature of the Inspector enables you to examine how the client-side human service operates in each step of its execution. the location of the error. The Inspector can also be used for problem determination and to identify the source of errors. . Parent topic:Modeling client-side human services 600 . The debugging feature of the Inspector facilitates a more thorough inspection than simply running the service. you use the Inspector in IBM Process Designer to iteratively test and observe how the client-side human service behaves at a detailed level. Playback sessions help capture important information from different contributors to ensure that the client-side human service meets the needs of everyone involved. and the line number. . Each playback session runs the client-side human service from the beginning to the end of the client-side human service. you can debug the client-side human service by using the Inspector in IBM Process Designer. Complete the coach and trigger the boundary event to transition out of the coach and move to the next step in the flow.Important: Because the playback window opens as a pop-up window. 2. 3. Click Run in the upper-right corner. configure your browser to allow pop-ups from the host that your Process Center is installed on. the playback window shows the coach. The playback window opens.Running client-side human services Authoring a client-side human service is an iterative process that can include several playback sessions. For coaches. the playback window shows the rendering of the coach so that you can complete the coach and move to the next step in the service flow. If the running activity is a coach. Each playback session runs the client-side human service from the beginning to the end of the client-side human service. To run the client-side human service. showing the running client-side human service. Before running the client-side human service. Open the client-side human service that you want to run. About this task While the client-side human service runs. complete the following steps: Procedure 1. Parent topic:Running and debugging client-side human services 601 . you might receive an error message if your web browser is configured to block popups. Results The playback window displays a confirmation message that the client-side human service completed successfully. a playback window shows the running client-side human service. Important: Because the playback window opens as a pop-up window. 2. If your client-side human service does not behave as you expected.Debugging client-side human services If errors occur while the client-side human service is running. Actions in the Inspector Icon Action Step Over Step Into Show Playback Window Refresh Cancel Debugging Session Description Move the service execution to the next activity in the flow. you might receive an error message if your web browser is configured to block pop-ups. The Inspector pauses the execution of the service flow before running each step and displays the variable values at each point. The debugging feature of the Inspector enables you to examine how the client-side human service operates in each step of its execution. Before proceeding with the debugging session. Click Debug in the upper-right corner. About this task Using the Inspector. Refresh the content of the service flow with the latest updates. The Inspector opens in the browser window. To debug a client-side human service. you can use the debugging capability to identify which step is at fault. you can incrementally step through the activities in your clientside human service so that you can observe how the client-side human service behaves as it runs. The error message is displayed in the playback window and on the sidebar in the Inspector. configure your browser to allow pop-ups from the host that your Process Center is installed on. Bring forward or reopen the playback window. Open the client-side human service that you want to debug. you can debug the client-side human service by using the Inspector in IBM Process Designer. Stop the service execution on a breakpoint before a coach is run and debug the coach. pausing on the first step after the Start event. Cancels the current debugging session before the client-side human service reaches the end. 602 . complete the following steps: Procedure 1. You can perform the following actions from the sidebar in the Inspector to debug the client-side human service:Table 1. Click Step Into to pause the execution flow before the coach is run. consult the documentation for your browser. Use your browser debugger or developer tools to set breakpoints in the source code for the coach. As the execution progresses. When you are ready to return to the Designer perspective. Click Show Playback Window to open it if it is not already open. For information about how to open and use the browser debugger or developer tools. Repeat steps 3 to 5 until you complete the client-side human service. click Step Over . C. 4. B. Examine the variable values to determine whether they are expected. Complete the coach and trigger the boundary event to transition out of the coach. the playback window shows the rendering of the coach. Ensure that the playback window is open. click Designer in the upper-left corner of the browser window. 5. 6. you can click Cancel Debugging Session to cancel the debugging session before the client-side human service reaches the end. Open the debugging window or the developer tools that are associated with the playback window. 7. If this activity is a coach. Alternatively. When the coach completes successfully. Go step by step through the code to observe how it behaves and identify any errors. Parent topic:Running and debugging client-side human services Related information: Tips for debugging coach view lifecycle method inside Human Services Tips for debugging coach views in Process Portal 603 . When you are ready to move on to the next activity in the client-side human service. the followed path is highlighted and color-coded indicators are added to the client-side human service diagram to mark the progress in the execution. the execution moves to the next step in the flow. If errors occur while running the coach.3. use the Step Into action to debug the coach: A. The Inspector moves to the next step in the service flow. D. Contact your system administrator.log and trace. The system administrator can enable tracing and check the browser console for additional information.Error: The \"${MODEL_ID}\" model with the \"${SNAPSHOT_ID}\" snapshot ID could not be loaded. Contact your system administrator. and the line number. The specified model could not be loaded from the repository. the system administrator can take different approaches to help resolve the error. The system administrator must verify that the specified model values are correct and that the model is present in the repository. Depending on what error occurred. For more information. and contact your system administrator for extra help. check the log and trace information in the SystemOut.Table 1. If the diagnostic information in the browser console is insufficient. . the location of the error. Common error messages for client-side execution of client-side human services Error type System error Error message examples Model loading error Error: The \"${MODEL_ID}\" model from the \"${BRANCH_ID}\" branch could not be loaded. Error: The engine encountered an unrecoverable error. 604 Description A JavaScript error occurred.Troubleshooting errors from running client-side human services Errors that occur when client-side human services run on the client side are logged to the browser console. The browser console provides the error type.log files. see the IBM Business Process Manager log files. The following table describes some of the common errors that you might encounter while running client-side human services in the web browser. Contact your system administrator. Correct the model and try again. The server returned an error. . Ensure that the model is syntactically correct. Server Error (401): Insufficient credentials to access the URL \"${URL}\".Error: The \"${MODEL_ID}\" model in the \"${BRANCH_ID}\" branch is invalid because it does not contain the \"${ELEMENT_NAME}\" element. Correct the model and try again. The system administrator must adjust the troubleshooting approach based on the specific content of the error message.Model validation error HTTP error Error: The \"${MODEL_ID}\" model in the \"${BRANCH_ID}\" branch contains no start nodes.The server responded with an error code ${STATUS} when accessing the URL \"${URL}\". Correct the model and try again. Verify that you have sufficient authorization to access the specified URL. 605 The model is incorrect.Server Error (404): The system was unable to access the URL \"${URL}\". Correct the model and try again.Error: The \"${MODEL_ID}\" model with the \"${SNAPSHOT_ID}\" snapshot ID is invalid because it does not contain the \"${ELEMENT_NAME}\" element.Error: The \"${MODEL_ID}\" model with the \"${SNAPSHOT_ID}\" snapshot ID contains no start nodes. Contact your system administrator. Contact your system administrator to ensure that the server is running. 5. If the version of a client-side human service running in Process Center is not the most recent version in the snapshot. cached version. Parent topic:Running and debugging client-side human services 606 . Certificate errors and the client-side human services playback Signer certificate errors might occur when you use HTTPs but have not imported your signer certificates.Client-side human service is not the most recent version in snapshot The caching behavior for client-side human services has changed to allow for better performance in Version 8. users should clear the browser cache to ensure that they are not accessing an older. To avoid certificate errors in the browser and ensure an error-free environment for your playback sessions. This may lead to inconsistent playback behavior. import the signer certificates before proceeding with the playback. Check with your administrator for instructions on how to import the signer certificates.5. Keyboard shortcuts that are available in Process Designer for client-side human services Action Delete Move Keyboard shortcut Delete key or Backspace key Arrow key Move all Shift + Arrow key Select Spacebar Select all Ctrl+A Multiple select Ctrl+Spacebar Clear selection Esc Connect J Switch modes F9 607 Description Delete the selected node or connection. Select all the graphical elements that are in the diagram. Table 1. you can perform many actions by using built-in keyboard accessibility features. Add or remove the focused node or connection to or from the current selection. Select the node or connection that has the focus. Move the selected node on the canvas in the direction that is specified by the arrow. Clear the current selection and the currently focused node or connection. Switch between the edition mode and navigation mode. The keyboard accessibility features help you go to and edit client-side human service diagrams in the web editor without using the mouse.Keyboard accessibility for client-side human services In the Process Designer web editor. Move all the graphical elements in the diagram in the direction specified by the arrow. . regardless of whether they are connected. Connect two selected nodes. You also use the disconnected-node navigation when you have disconnected nodes on your canvas.In the disconnected-node navigation. Zoom out of an area of the diagram. Zoom in on an area of the diagram. Undo the last undo action. 608 . use the arrow keys to navigate through connected nodes and their connections. Using the quick-add function. You cannot navigate through disconnected nodes by using the connected-code navigation. Save the changes. you can use the quick-add function in the web editor. Reverse the last action that you performed.In the connectednode navigation. . ignoring connections. The nodes are traversed in the order in which they were created. you can add one or more nodes to a client-side human service diagram in one step. use the arrow keys to navigate through the nodes in your clientside human service diagram. Open the inline editor for the first editable label of the currently focused graphic element.Change navigation style F8 Save Undo Ctrl+S Ctrl+Z Redo Open inline editor Ctrl+Y F2 Zoom in Ctrl+Plus(+) Zoom out Ctrl+Minus(-) Zoom reset Ctrl+0 Switch between the disconnected-node navigation and connectednode navigation. Use this shortcut only in the navigation mode. Display the current area of the diagram with the default zoom factor.Adding nodes to client-side human services by using the keyboard To add nodes to client-side human services by using the keyboard. Parent topic:Modeling client-side human services Related information: Accessibility in IBM Business Process Manager 609 . Using the quick-add function. to add three different services to the client-side human service diagram. After the services are added to the canvas. services. Add an exclusive gateway. Open the Process Designer desktop editor. and end events. The nodes that you can add through the Quick Add window can include one or more coaches. you can use the Quick Add window to create a list of nodes that can be added to your client-side human service in one step. client-side scripts. In the Properties view of each newly added node. Add an end event.The types of nodes that are available for you to quickly add to the canvas match the tools in the palette. Enter the node types that you want to add.Table 1. you can use the quick-add function in the web editor. Add a client-side server script. For an entry that does not match any of the node types that were listed previously. Add an intermediate event. 2. complete the following steps: 1. Open the client-side human service that you want to work with. The default implementation is a stay-on-page event. and then press the Q key.To add more nodes of the same type to the diagram. 3. ensure that the focus is on the canvas. If necessary. and then click Add. 4. Procedure To add nodes to the client-side human service diagram by using the keyboard. The Quick Add window opens. you can update the properties in the Properties view of each service. a client-side script is added to the diagram. For example. 5. Node types that are available for you to quickly add to a client-side human service Node type coach script service exclusive end intermediate Description Add a coach. About this task Instead of using the mouse and the tools from the palette to add elements to the client-side human service diagram one at a time. 610 . use the Tab key to bring the focus back to the canvas. Add an activity that calls another service. you must add three service entries to the list. update the node name and its properties as required. you can add one or more nodes to a client-side human service diagram in one step.Adding nodes to client-side human services by using the keyboard To add nodes to client-side human services by using the keyboard. add more entries of the same type to the list. intermediate events such as stay-onpage events or postpone events. In the Diagram view. separated by pressing Enter. Click Save all to save the configuration of the client-side human service. Parent topic:Keyboard accessibility for client-side human services 611 .6. create a general system or integration service with a server script that contains your script logic. .Input/output variables . Consider the following points when you plan to convert a heritage human service into a client-side human service.If the server script includes complex server-side operations.addresses[0] = {}. as specified in the following Important note. For some components.customer. extra configuration might be required. depending on how the components are used in the service flow.local. If your script includes instantiation logic.local. You can copy and paste the server script content into the client-side script.customer= {}.Based on what the server script for the heritage human service includes.addresses = [].firstName = "Jane". tw.city = "Boston".local. which requires you to re-create some of the service flow. you must convert the heritage human service into a client-side human service. .local.In the web editor. When you re-create the service flow in the web editor. // To instantiate and populate an array tw. . it might require adjustments. create a client-side script in the client-side human service and enter the same logic into it.local.Re-create the coaches for the client-side human service in the web editor.lastName = "Doe". .If the server script only requires simple access to or simple manipulation of local variables. Important: The server script syntax in the heritage human service is different from the client-side script syntax in a client-side human service. tw.addresses[0]. For client-side human services. you re-create some of the components and artifacts in the same way that they were created for the heritage human service.customer. In your client-side human service. 612 . . choose a suitable replacement according to the following guidance: .Re-create your input and output local and private variables by using the same variable types. for example// To instantiate and populate a complex variable tw. tw. use a service to call the general system or integration service that you created.local.Coaches . click the plus sign next to Localization Resources and select a localization resource bundle to add to the client-side human service.Server script . ensure that you use the standard JavaScript syntax to instantiate objects in the client-side script.Localization resources . tw.Heritage human service to client-side human service conversion To gain the improved performance of a client-side human service and use the new features provided by the client-side human service. instead of the server script syntax that is used in a heritage human service. To migrate integration elements such as Invoke UCA or Intermediate Tracking Event from an existing heritage human service to a new client-side human service. and then call this integration service in the new client-side human service.If you used a validation service to validate your coach output. combine multiple service calls where possible. create a general system service with a server script that holds your logic and use it as described earlier. See Example: validating a coach in a heritage human service. . you have two choices: .Heritage coaches . create an integration service that contains these constructs.If the server script logic includes complex operations or requires access to private or confidential data.Server-side validation . Tip: For optimal performance. modify it to include an error end event that passes the validation errors back to the client-side human service. // To create a Date variable tw. if the validation succeeds. See Example: validating data in a coach that is used in a human service. If you instead used a server script to validate your coach logic.// To instantiate a String variable tw. However.Support for heritage coaches is not provided in client-side human services. instead of calling a validation service followed by a service that performs some work. .local. continue using it.If your server script logic requires simple access to local variables and does not require access to private or confidential data. continue using the heritage human services that provide the required support.customerID = "12345".dueDate = new Date(). . .local. and place your validation logic there. create a client-side script in your client-side human service. performs the work. Parent topic:Creating user interfaces for business processes 613 . combine these into a single service that internally performs the validation and. For heritage coaches.Server integration . For example. in general you take the following steps: 1. The upgrade is optional. If the coach views that your coach will use do not exist. 4. In the human service diagram. If you are revising an existing coach. add a dependency to these toolkits. Although you can do some of the steps in any order.8. Drag coach views or variables onto the layout of the coach. the coach continues to use the existing dependency.0. your goal might be to build a mock-up. 3.5 toolkit uses Dojo 1. you create one address field coach view.Building coaches You can build a coach as the user interface that process participants or case owners use to interact with a service. see Developing reusable coach views. These coach views can be the coach views that you created earlier or the stock controls. If there are toolkits that contain artifacts that your coach can use. If you upgrade the coaches toolkit to version 8. Use the mock-ups to identify elements in the coach that are common with other coaches. create them. Instead of creating the two sets of address field in the coach. you can upgrade the dependency to a different snapshot of the toolkit. The variables are business objects and their parameters that are defined for the human service . 5.The best layout for the user interface elements in the coach. If the variable type does not have an associated coach view. For example. the Designer puts a text stock control that is bound to the variable. You can then use this information to decide which parts of the coach you can implement as reusable coach views. which helps them make the appropriate decisions. add the coach to the diagram and then doubleclick it to edit it. You can then use it for both sets of address fields. if you drop a variable that is of the String type. After you complete the first stage to design the look of the coach. Identify the following information: . If you do not do the upgrade. For example. For the variables.5. This step requires you to create bindings between the coach controls and the data structures (variables) that represent the business data in your IBM® Business Process Manager processes or cases. after you create the mock-up.Important: The coaches 8. For information. the Designer puts a placeholder message on the layout 614 . the Designer puts the coach view that is associated with the business object or parameter type onto the layout. review the coaches in the process application to assess the impact of the upgrade in Dojo version.6 with AMD (Asynchronous Module Definition). The mock-up contains static elements to visualize what data the coach needs at run time and where the coach displays the data in its layout. you then feed real business data to the coach controls. and files. These artifacts include business objects. coach views. The dependency is to a particular snapshot of the toolkit. you see that your coach contains two sets of identical address fields. In the first stage of designing a coach.The elements in the coach that are reusable. 2. Create one or more mock-ups for the coach. . Your process participants or case owners can then interact with the business data. Building a coach is often an iterative process in which you loop back to refine the coach as you build it. Tip: For elements in the coach that you do not plan to reuse. Custom coach views might not provide you with this functionality. For example. . If needed. define their visibility. You can embed sections within other sections. see Example: creating a tabbed coach. For information. For example. These CSS classes are defined elsewhere such as in the coach view definition as inline CSS or in a CSS file uploaded as an included script. 11. Wire the coach into the service flow by connecting boundary events that the coach views fire to the appropriate elements in the service flow. Many coach views contain configuration options that you can set for each instance. for text fields and buttons. drop them into a horizontal section. For information about validating coaches in client-sided human services. use validation to check its data. select them and then change their properties. For information about validating coaches in heritage human services. You can also override the styling of the coach view instances by adding CSS classes and attributes as HTML properties. If the coach views support having different types of visibility. contact the developer of the coach view to add support for this functionality. 10. 8.Validating coaches in heritage human services To ensure that a coach that is in your heritage human service passes valid data in the flow. see Validating client-side coaches using client-side validation and Validating client-side coaches using server-side validation. Review the coach and update the coach or the coach views that it contains until the coach looks and behaves as you intend. You can also drag fields within a variable directly onto the coach. for text instructions for the user.Important: You can set the visibility of the controls in the Coaches toolkit. In the Designer or the Inspector. if you want two coach views beside each other. You can then use the placeholder to manually specify the binding between the variable and a coach view. use sections. validate the data in the coach. click . To lay out the coach views in the coach.instead. you can drop the appropriate palette component onto the coach. 9. For example. change the label to something useful for users. you can drop an HTML element and add the text as HTML code. If a custom coach view does not support setting visibility. For examples of dragging a coach view and variables onto a coach. see Validating coaches in heritage human services. 7. Parent topic:Creating user interfaces for business processes Related tasks: Enabling tracing for Coaches Related information: Stock controls Controls in the Content Management toolkit Boundary events 615 . To edit the coach view instances. see Setting the visibility of coach views. 12. 6. Building heritage coaches 616 . var2 == ""){ tw.addCoachValidationError(CoachValidation coachValidation. } if (tw. For example.addCoachValidationError(tw. Coach1 is being validated by a server script and Coach2 is being validated by a validation service: The following steps describe how to validate by using a server script. see Example: validating a coach in a heritage human service. The validation element can be a nested service or a server script.coachValidation. set the Fire Validation property to Before. The server script is the simpler implementation although the nested service provides greater flexibility. select the line for that boundary event. add JavaScript code that identifies problematic data. Use the tw. In the properties for the line.var1". "tw. The first string contains the full variable path to the data element with the problematic data. In the following diagram. The message identifies what is wrong with the data and tells the user 617 .coachValidation. About this task In a heritage human service.local.coachValidation parameter is the system variable that contains the validation information. Add a server script to validate the data to the human service diagram. 3.system. "Enter a value for field 1"). The coach has a validate icon to indicate that you can now connect the coach to the validation script.system. 2. For information about using a validation service to validate coach data.system.system. String errorBOPath. Procedure 1. To ensure that they have a value. To validate the coach data before a particular boundary event occurs. In the Script properties. Select the script of the validation pattern.Validating coaches in heritage human services To ensure that a coach that is in your heritage human service passes valid data in the flow. use code like the following example code:if (tw. String errorMessage) API to add the error data to the coachValidation system variable. you validate the data that is in the coach before the flow proceeds to the next step in the service flow.var1 == ""){ tw.system. They are bound to var1 and var2. use validation to check its data.addCoachValidationError(tw. You validate the data by adding a validation element and a stay on page event.local.local. you want two fields to have a value. } The tw. The second string is the message for the user. "Enter a value for field 2"). "tw.var2".system.local. . there is nowhere to display a validation error if one occurs. Parent topic:Building coaches Related information: Handling errors in client-side human services Example: validating a coach in a heritage human service 618 .A coach in a heritage human service can use only one validation service or server script to validate its data. the system processes the boundary event to move to the next step. . Connect the validation script to the Stay on Page event. If the data is valid.how to fix the problem. Add a Stay on Page event. Connect the validate icon of the coach to the validation script. 5. This construction loops the flow back to the coach if the data in the coach is not valid. users see the appropriate message when they hover over an indicator. 4. Important: .If the data element that is being validated is not bound to a coach view. However. If the validation script provides error messages. more than one coach can use the same validation service or script. The system passes error information back to the coach and users see an indicator beside the coach view with the problematic data. code the validation server script to remove formatting before it validates the text contents.If a coach view that is being validated contains rich text. Developing reusable coach views To contain functions or user interface elements that another coach view or a coach can use. IBM Business Process Manager provides two sets of basic controls that include standard user interface elements such as text fields. These changes might have unintended consequences in other process applications.6 in any order. On the Overview page. documentation. 5. About this task You can create a coach view by using the Designer interface of IBM® Business Process Manager. Creating a coach view can be an iterative process in which you do steps 3 . For information about JavaScript IDs. 3. default is a reserved word in JavaScript. After you click Finish. The new coach view can be in a toolkit or in the process application.1. see Defining coach view behavior. see Adding variables to coach views. update the appropriate pages and retest. 619 . 2. images. For information about these controls. The risk of this approach is that if someone edits that coach view. In the window that opens. Define what the coach view displays to users in the Layout page: For information about adding coach views and other palette and library items to the coach view. Continue the iterative process of updating and retesting until you are satisfied with the look and behavior of your coach view. 6. create a coach view. These controls are implemented as coach views that you can use to develop more complex coach views. create the coach view in a toolkit. click the plus sign next to User Interface and select Coach View from the list of components. Unless you are basing the new coach view on a template. provide information about the coach view. That is. For information about adding behavior to your coach view. For information about defining the data used by the coach view and defining how users can customize it. define the behavior for the coach view. the changes apply to all instances of that coach view. Restriction: The name of the coach view must be a valid JavaScript ID with the following exceptions: it can have spaces and it cannot have underscores. the editor opens the new coach view. To reuse the coach view in multiple process applications. The benefit of this approach is that the coach view is available to all process applications that use that toolkit. see Stock controls. In the library. You might start by following the instructions in the order that is listed in the procedure. On the Behavior page. see Annotated ECMAScript 5. and so on. see Providing information about coach views 4. you can use names like My Coach View or MyCoachView. but you cannot use names like My_Coach_View or default. start with a blank coach view. Procedure 1. define the variables that the coach view uses. consider creating the coach view in the process application to limit the changes to that particular process application. type the name of the new coach view. and icon images. If you think the risk is too high. On the Variables page. For information about adding tags. Based on the results of your test. repeat steps 3 . 8. during collaboration the default highlighting behavior is implemented based on a unique DOM ID. . but are developed outside of Process Designer. However. Review the configuration for the coach view and update it if necessary. To access these assets from a coach. For example. style sheets. E. .Providing information about coach views You can help people use a coach view by making it easier to find and providing information about it. Bind the variables that the coach view uses to appropriate data. Based on the review. define the CSS classes and attributes as inline CSS or define them in a CSS file and upload that file as an included script. connect the coach to appropriate nodes in the flow. The Coach framework calls Ajax services using the BPM REST API in taskless mode. B. to generate a URL for an AMD module which is contained in a zip file. AMD modules or other assets that are part of a coach view. you can use the $$viewDOMID$$ placeholder keyword.Adding variables to coach views You can define the data used by the coach view and the ways in which users can configure it.Defining coach view behavior You can define the behavior and appearance of a coach view by adding JavaScript and styles and by defining functions in its event handlers. in the Layout page add CSS classes and attributes as HTML properties to these instances. add the coach view to a coach. To play the human service or heritage human service in Process Inspector or Process Designer. D. In a human service or heritage human service. Test your coach view: A. 9.Generating a unique ID for a coach view In some situations you might want to use the ID attribute for your DOM elements within a coach view. For example. . . Ensure that the coach is part of the service flow. . you might need use a global JavaScript function to generate the URL of the asset. That is. Review the look of the coach view and how it functions. To apply a custom styling to the coach view instances that your coach view displays. At run time. all DOM IDs must be globally unique. . click .see Defining the contents of coach views 7. .7 to make the appropriate adjustments to the coach view or the items it contains or refers to. C.Generating URLs of managed assets Managed assets are images.Defining the contents of coach views You can define what a coach view displays to users at runtime. if you cannot trace from the start node to the coach. Keep iterating through reviews and updates until you have the results that you want. 620 . this keyword will be replaced by the coach view DOM ID.Calling Ajax services from coach views You can invoke Ajax services from within coach views. To ensure a unique ID. On the Behavior page. Parent topic:Creating user interfaces for business processes Related tasks: Enabling tracing for Coaches Related information: Coach views 621 . If you want to improve performance for the coach view. . This diagram also shows the control that fires the boundary event.If you want your view to be selectable as a template when someone creates a coach view.options. .If you want coaches or coach views that contain your coach view to display a label at design time. } "123") { . Also. select Prototype-level event handlers.Add one or more tags to the coach view. Selecting this option means that the event handlers for the coach view are in the prototype and not in every instance. The 622 . The performance gain comes from having one set of the event handlers per coach view definition instead of having a set per coach view instance.context.myVariable = "123". see Example: showing the label of a complex coach view for information on how to display the label at runtime. select Supports a label.. For example. view:this. Access the variable in the load Access the variable in the load event handler:if(myvariable == "123") { event handler:if(this. documentation. select Use as a Template. For prototype-level event handlers. describe the boundary events that your view fires.. . . the JavaScript code that you use to create and access variables differs between coach view instance-level event handlers and prototype-level handlers. The following table shows the coding difference for the two levels of event handlers: Instance-level event handlers Prototype-level event handlers Define the variable in the inline Define the variable in the inline JavaScript of the coach view:var JavaScript of the coach myVariable = "123". If you do not specify a tag.. In a human service diagram.If you want your coach view to use named boundary events to move to the next step in the service flow. provide information about the coach view that helps people who reuse your view in their own coaches or coach views.. you see these boundary events as wires.get("value").In the Documentation field. Procedure Provide information such as tags._metadata. you can find your coach view in the No Tags category. and icon images for the coach view in its Overview page: .myvariable == .label. However. . you must use the this keyword.Process Designer uses these tags to categorize the coach view on the palette and within the library. To have the coach view access the label value in the runtime environment.Providing information about coach views You can help people use a coach view by making it easier to find and providing information about it. add the following code as inline JavaScript in the Behavior page of the coach view: this.Tip: Add a content box to your coach view so that coach views that are based on the template have an area in which users can drop content. select Can Fire Boundary Event. } You can also look at the stock controls for examples of the coding difference. you can specify HTML and JavaScript to create and enhance the design-time appearance of your coach view.stock controls of the Coaches toolkit in version 8.0 and higher have prototypelevel event handlers. see Configuring the design-time appearance of coach views. The stock controls in earlier versions of the Coaches toolkit have instance-level event handlers. Parent topic:Developing reusable coach views Related information: Defining the contents of coach views Configuring the design-time appearance of coach views Defining coach view behavior Adding variables to coach views 623 . .5. For information.If you are using the Process Designer web editor. zip file. You can add these files to the library as individual web files or package them in a .Note: The '!' notation to reference a file inside an archive is supported only in inline CSS behavior. the system does not find the images if you package a . repackage them. There are a few restrictions on this design-time styling support: . However. For example.zip file. and then replace the . the following media type statements are processed at design time: @media screen ….zip file in Process Designer. If you are working in the web editor. If you add .js and . Instead. only media queries with a media type screen are parsed and only the max-width and min-width specifications are applied at design time.css'). the following statements are not processed at design time: @media not screen @media not print @media not (tty and screen) . the coach view styles specified in .zip file means that they maintain their relative relationships. You cannot edit . allowing you to see how the coach view will appear at run time without having to run or test your coach view. If you are pointing to an image file in a . use the following format for the URL: file.Imports within included scripts and inline CSS will only be processed to one level of embedding.Add existing script and style sheet files from the library by using included scripts.zip file. Subsequent coach views or coaches within human services will not have design-time styling applied.css files as individual web files. This design-time styling only supports simple syntax. @media all @media (min-width: 520 px ) However.css file and include the images that it refers to using relative links.extension. . . if you have inline CSS that includes the statement @import url('File1. Procedure Define the functionality and appearance of the coach view in its Behavior page: . you must edit them externally.zip!path/ file.Defining coach view behavior You can define the behavior and appearance of a coach view by adding JavaScript and styles and by defining functions in its event handlers. For example. for example. the system finds the images. these files are reusable . you can edit them in Process Designer. If you have large or complex coaches and coach views. the design-time application 624 . Typically. then the css within File1 is reflected at design time.css files.zip file and package the images that it refers to in a different .If you are using Internet Explorer 9. if you package a .Add local custom styles to the coach view by using inline CSS.zip file and add that file as a web file.css file in one . Packaging the files in a . design-time styling is only applied for the first 25 coach views or human services that are opened.css files that are packaged in a .If you use media query statements in your CSS.css files and inline CSS are applied to the coach view in the Layout tab. but any import statements inside File1 are not reflected at design time.zip web file with your updated . Add conditional styling to handle differences between browsers and media types.css file for Microsoft Internet Explorer and a different . . go to the Layout tab. see Example: creating a Select control using custom HTML.trigger(callback) at the appropriate time. If the user's screen is 600 pixels or less in width. . . . To turn design-styling back on for the session. 625 . For example. register the aliases for the dependent modules by using AMD dependencies. 2. To fire the event.css file. 3. In the IE Condition or Media fields.To insert code like <meta> tags into the header of the coach view. The editor contains a code snippet.If necessary. you can add styles for tablets to use a smaller font for labels and reduce padding. Note: Any inline JavaScript styling and any styling conditions entered in the IE Condition and Media fields are only processed at run time and are not reflected at design time. The editor does not show validation messages for code snippets.Improving coach view performance To improve the performance of a coach view. add the condition that applies the styles in the .css file. the coach view uses the styles in the .css file as an included script.context. the specified coach view styles are not applied. Add screen size-specific styling or browser-specific styling to a . Script functions can then use these aliases to refer to the modules. You use conditional styling to apply the appropriate file. add a condition like screen and (max-width: 600px) to the Media field.css file for other browsers.of styles might cause some performance issues. code the JavaScript to call this. .If your coach view requires modules that are written in the AMD style.Define common variables and functions for the event handlers of the coach view by using inline JavaScript. For information. For an example of using dependent modules. For example. right-click anywhere on the canvas and select Disable design-time styling. If you selected Can Fire a Boundary Event in the Overview page. right-click on the canvas and select Enable design-time styling. For example.css file instead of default values. you can apply one . use Header HTML. The conditional styling overrides the default styles when the condition applies. see Improving the performance of coach views with Dojo build layers. see Adding custom AMD modules. To disable design-time styling for the current session.css file contains styles for a tablet presentation. define the functions that the coach view uses in the appropriate event handlers. For the rest of the session.Add custom Dojo build layers to improve the performance of the coach view. . For information about registering AMD modules. see Accessing a child coach view by using a control ID. You can also add conditional styling by adding inline JavaScript and inline CSS. if the . For more information. For information about accessing parts of the DOM. see Event handlers for the view object and the load event handler code in Example: creating a Dojo button control and Example: creating a jQuery button control. To add conditional styling: 1. add code to fire the boundary events. Add the . you can add custom Dojo build layers to it. . .Accessing a child coach view The control ID is the unique ID of the control within the parent view. or for more advanced configurations. custom HTML and JavaScript. . You can use the control ID to access a subview instance at run time. you can customize the appearance of your views to help interface developers visualize how the coach view will appear at run time. By including palette and preview images. Parent topic:Developing reusable coach views Related information: Providing information about coach views Defining the contents of coach views Adding variables to coach views 626 .Configuring the design-time appearance of coach views You can configure your coach views to enhance the design-time experience for other interface developers who are reusing your coach views..Adding custom AMD modules You can use custom AMD (Asynchronous Module Definition) modules in your coach views. zip file as a managed web file. Process Designer uses this format to generate the appropriate code in the HTML for the coaches that contain the coach view. Procedure 1. You can use the layers to improve performance by optimizing the loading of the modules without sacrificing modular development. Upload that . your coach view can include the modules that it depends on in one file or small set of files. You can specify different layers for each mode. each one a layer. If you have custom code./* 1 @dojoConfigUpdateStart 2 if (dojoConfig. replace the name and location values in the Dojo configuration section and replace the names in the layer section. copy the comment block into these coach views.@layerRequiredStart and @layerRequiredEnd contain a JSON structure with two optional properties (debug and non-debug). The isDebug configuration setting in the administrative console determines which mode is in effect. The following example shows the comment block for adding Dojo build layers.zip. Package your Dojo build layer in a . The comment block consists of two sets of tag blocks: .@dojoConfigUpdateStart and @dojoConfigUpdateEnd contain normal JavaScript code that updates the global dojoConfig variable before the system loads the Dojo AMD loader. For your implementation. such as myLayer. Process Designer combines it so that the generated page contains only one copy of the layer code. For information about Dojo build layers and how to create them by using a transform. The build layer definitions must be in a specific format at the start of the inline JavaScript for the coach view. Tip: If you have multiple coach views that are adding the same layers. B.Improving coach view performance To improve the performance of a coach view. . On the Behavior page of the coach view.zip file. These files. The layer files must be built with the Dojo version that is compatible with the Dojo version that your coach view uses. 2. you can add custom Dojo build layers to it. transform it into a Dojo build layer. If the layer content is the same. see The Dojo Build System. 3. add a specific comment block at the beginning of the inline JavaScript. Prepare your custom JavaScript: A. IBM® Business Process Manager has two modes: debug and non-debug. About this task With the Dojo build system. Each property is a JavaScript array type that contains the full name of the layers for each mode. reduce the number of HTTP requests that are needed by the application that contains the coach view. These layers can be custom code or be third-party Dojo layers. The full name is the package name and the layer file name.isDebug) { 627 . location: com_ibm_bpm_coach.1 Using a comment prevents the comment’s contents from being run as actual inline JavaScript of the coach view. In this example. } @dojoConfigUpdateEnd @layerRequiredStart 5 { "nonDebug":["com.6 The name of the package and module within that package for the layer to use in this mode.mycompany.dashboards'.push({ name: 'com. 'SYSD') + "/com/mycompany/dashboards" }).dashboards/dashboardsMore"].packages. 6 "debug":["com. . com_ibm_bpm_coach. 'SYSD') + "/com/mycompany/dashboards" 4 }). the non-debug mode loads two layers and the debug mode loads one layer.mycompany. com_ibm_bpm_coach. 3 location: com_ibm_bpm_coach. "com. } else { dojoConfig.mycompany.assetType_WEB.getManagedAssetUrl('myLayer_debug.dashboards/dashboardsDebug"] } @layerRequiredEnd * / .5 The start of the layer section .2 The start of the Dojo configuration section . see many of the coach views in the Dashboards toolkit.push({ name: 'com.zip'.dashboards'.assetType_WEB.mycompany.dashboards/dashboards".mycompany.4 The location of the managed file that contains the package .packages.zip'.dojoConfig. For more examples of how to add layers. Parent topic:Defining coach view behavior 628 .3 The namespace for the package .getManagedAssetUrl('myLayer. zip.zip'.js file and add the following package map code for AMD modules that are called myModule and myOtherModule:require({ packages: [ {name: 'myModule'.In the Alias column.assetType_WEB. 3. .zip'. location: com_ibm_bpm_coach.6 AMD loader.zip file. Registering a module involves assigning an alias for the module because the coach view accesses the module by using its alias. 'PROJECT') + "/path/to/myOtherModule" } ] }). 2. location: com_ibm_bpm_coach. With this loader. The /path/to/myModule is the path in the . Prepare your AMD package: A. com_ibm_bpm_coach. Create a JavaScript file to define the package map for your AMD modules. If the module is in a referenced toolkit. On the Behavior page of your coach view. Package your AMD modules in a .zip file as a managed web file.getManagedAssetUrl('myPackage. The PROJECT parameter contains the acronym or short name of the process application or toolkit that contains the . 'PROJECT') + "/path/to/myModule"} {name: 'myModule'. About this task IBM® Business Process Manager includes the Dojo 1. D.8. type the alias that you use in the code to refer to the module.assetType_WEB. com_ibm_bpm_coach. Upload that . Procedure 1. Click Add and then specify the following information: . create the myPackageMap.zip file such as myPackage. the PROJECT parameter is optional.getManagedAssetUrl('myPackage. If the class for the AMD module is at the root of the managed web file. If the module is in the current process application. declare the dependency on the AMD module by using a path like myPackage/path/to/myModule. select AMD dependencies. In your coach view code.In the Module ID column. B. do not include the /path/to/myModule parameter. On the Behaviorr page of the coach view.zip file to the AMD module class. Parent topic:Defining coach view behavior 629 . B. C. you must include the PROJECT parameter to ensure that the coach view can use module in the context of the process application. Register each AMD module in your coach view: A. For example. add the JavaScript file as an included script. use the alias to access the functions of the AMD module.Adding custom AMD modules You can use custom AMD (Asynchronous Module Definition) modules in your coach views. you can package custom AMD modules and then register a dependency on those modules in your coach view. Related information: Developing reusable coach views Example: creating a Dojo button control 630 . In view-based coaches.getSubview("myCheckbox")[0]. Example 631 . 2. Important: The control ID of a view-based coach is different from the control ID of a heritage coach. requiredOrder) method. Get the control ID by using the this. In the Behavior page of the coach view editor. it is set to false.Accessing a child coach view The control ID is the unique ID of the control within the parent view. which you can change. select the control that you want to access at run time. The default is false.A Boolean value. If set to true. select General. By using the data-viewid attribute. About this task At design time.context. C. B.subViewID . Procedure To use a control ID in your code: 1. At run time. In the properties area. If the result does not contain a set of repeatable objects.context. and then click the Coaches tab. view developers can locate the nested view because data-viewid is unique within its parent or enclosing view. each control in a coach is given a default control ID. In the design area. the control ID is the value for the data-viewid attribute of a <div></<div> tag. By default. This control ID is unique within the parent view. The control ID field contains the unique ID for the control. You can use the control ID to access a subview instance at run time. This is not the case in view-based coaches because coach views are reusable and you can have multiple views in a coach. set the second optional parameter to true. You can use the control ID to access an instance of the child coach view at run time by identifying the <div></div> that contains the instance. See the following example for details. If you need the array in the same order as your document order. the method returns the array of view instance objects in the same order as the document tree.requiredOrder . The method returns an array of nested view instance objects.The id parameter of the <div></div> tag of the nested view instance object .getSubview(subViewId. the parent view is rendered as a <div></div> tag. Enter your code to interact with the nested view instance as appropriate. Open the service that contains the coach that you want to work with. which contains a nested <div></div> tag for each child coach view. add JavaScript code: A. for example this. B. . specify the first index of the returned array list. Determine the control ID: A. The control ID of a heritage coach is the div node ID. getSubview("myCheckbox")[0]. } Parent topic:Defining coach view behavior Related information: Generating a unique ID for a coach view 632 .coach.Checkbox" data-binding="" data-config="config2" data-viewid="myCheckbox" data-eventId="" > The following code checks to ensure that the check box is selected (set to true).The following example has a coach view that uses a Check Box stock control.Snapshot_fc633c7d_3b4f_44db_82c1_cfc7ac8b5647.ibm. the user is prompted to check the check box before proceeding. the html rendered is shown in the following code snippet:<div id="div_2_1" class="ContentBox" data-view-managed=false> <div id="div_2_1_1" class="Checkbox CoachView" datatype="com.if (this.bpm. The check box is a subview of a parent content box view. }else{ alert( "Check the checkbox").get("value") == true) { return true.context. return false. At run time. If not.binding.context. If you want to bind the coach view to a managed asset at design time. Procedure 633 . . then you can set the position of the label on the canvas by specifying the Preview Label Position. . 1.If the coach view has a UI that is a result of HTML or JavaScript code and not other coach views. By including palette and preview images. the entire image is stretched. 2. giving interface developers a more accurate idea of how their coach views will look to application users. or for more advanced configurations. If you specified a layout image and you set the preview label position to Center. you can specify the parts of the image that you want to stretch in the pixel coordinates fields. Using HTML and JavaScript code. select Use URL binding. Typically. your coach views can have a design-time appearance that more closely resembles the view's runtime appearance. Advanced options for configuring design-time appearance of coach views The Process Designer web editor offers more advanced options for configuring the design-time appearance of your coach views. For example. Parent topic:Defining coach view behavior Basic preview options About this task Configure the design-time appearance of your coach view on the Overview page in the coach view editor. custom HTML and JavaScript. if you are using the Process Designer desktop editor. However. any code in these files that position the label overrides the value specified for Preview Label Position. the layout image stretches to fit the label text. Procedure . If you enter values into these fields.Specify an image file to use as a palette icon for your coach view. In some cases. the exact same code that is used for the runtime coach view can be leveraged in the coach canvas. the image controls use this setting so that they display the image that they are bound to in the Process Designer canvas.Configuring the design-time appearance of coach views You can configure your coach views to enhance the design-time experience for other interface developers who are reusing your coach views. If you are using the Process Designer web editor and you have specified an HTML snippet file or the Helper JS file (or both). the image stretches only between x1 and x2 and y1 and y2. . By default. specify a layout image to display on the canvas at design time.If your coach view supports a label. you can customize the appearance of your views to help interface developers visualize how the coach view will appear at run time. you use the center label position for UI elements like buttons. each can be uniquely placed in the HTML preview. The JavaScript handler can work in conjunction with an HTML snippet or it can handle the entire preview itself. but the names must be 634 . Add external files to your process application or toolkit. The following is an example HTML snippet: <div> <h2 class="DesignLabel"></h2> <div class="DesignContentBox" data-designContentBoxID="ContentBox1"> </div> 2. Note: The Design* class names are reserved by the editor.The simplest way to provide a design-time appearance for coach views that accurately reflect the run time appearance is via an HTML snippet. the data-design* attribute names should be avoided. . The JavaScript handler consists of a JavaScript file with a mixObject defined. . This file should be an HTML file with a snippet that represents the view. Similarly. A JavaScript handler allows for manipulation of the design time DOM in reaction to model changes. . Snippets should not use classes matching this pattern. then selected in the advanced preview section in the coach view editor. For example: <div> <button class="DesignLabel"></button> </div> The HTML snippet has some features to enable content boxes and labels to be placed appropriately. If multiple content boxes are declared.If an HTML snippet alone cannot provide the design-time preview experience that you want. select the file containing the HTML snippet. If this class is used. The editor places the label string at the inner HTML content of this element. then the element must also have the data-designContentBoxID attribute defined. if the coach view supports a label. then the editor will place the content box instance at the end of the view's rendering. but there is not a div in the HTML template with the DesignContentBox class and matching data-designContentBoxID. and the label is applied and updated to all elements. The mixObject can implement one or more functions which the editor calls during the editor lifecycle. You can also define additional functions.Class: DesignContentBox . Create an HTML snippet. This file should be an HTML file with a snippet that represents the view. 1.. The HTML snippet is uploaded as a managed asset. you can also specify a managed file containing a JavaScript handler. as described in Adding managed files. If a content box is declared in the layout of the coach view. 3. In the Advanced Preview section of the coach view Overview tab.Class: DesignLabel . This attribute should be set to the control ID of the declared content box.This class is used to indicate where a declared content box should be located in the preview. A snippet can have multiple labels.This class is placed on the HTML element that represents the label. place(button. 635 .create("div"). function(domConstruct){ var buttonDiv = domConstruct.labelTextDom = document. var button = domConstruct. The following is an example of a simple JavaScript handler that provides a preview label and image for a button control. buttonDiv).coachViewData. then it should be placed in the this. callback().coachViewData object.data = propertyValue.context.context.context. this.coachViewData.var mixObject = { createPreview:function(containingDiv.create("button").context. }.hitch(this.appendChild(this. For more information about the design-time preview APIs. for example. this. see Event handlers for coach view design-time preview.labelTextDom){ this. } }. coachViewImpl_calcValue().place(buttonDiv. containingDiv). domConstruct.lang.createTextNode(labelText). Both the function naming convention and instance variable storage location are used to prevent conflicts in future versions of the product. button. domConstruct.prefixed with coachViewImpl. })). If you want to store additional information on this. labelText.labelTextDom.coachViewData. callback){ require([ "dojo/dom-construct"]. propertyValue){ if(propertyName=="@label" && this.labelTextDom). propertyChanged:function(propertyName. }. use a list (array) of NameValuePair instead of a business data variable with the map type. This ensures that the variable and its properties are all typed. For service types.Adding variables to coach views You can define the data used by the coach view and the ways in which users can configure it. For example. Restriction: To avoid errors with binding a map to an instance of the coach view. .To associate the coach view with data. and can be understood by the server. Coaches and coach views that contain your coach view display these options as configuration properties when users select your coach view in the layout. The coach views that this coach view contains can bind to the associated data object or one of its parameters if it is a business object. For information. If you put a Button instance into a coach view. A data association is not mandatory.To provide translations for the text of your coach view. Parent topic:Developing reusable coach views Related information: Defining coach view behavior Providing information about coach views Defining the contents of coach views 636 . The users can then configure the instance by using the options that you provided. you can see Allow multiple clicks when you view its properties.To provide users with ways to customize coach view instances. see Localizing user interfaces. add configuration options. . Procedure Define the variables that the coach view uses to store its association with business data and how users can configure the coach view in its Variables page. add data such as a business object. you must specify a default service to identify the signature of the service. . A coach view can have only one associated data object. the Button stock control has the allowMultipleClicks configuration option. add resource bundles by adding localization resources. Configure the coach view instance by specifying or setting a value for each option or by assigning a variable if that choice is available. and other coach views. For each item that you dropped onto the layout page. you see a warning. the Safari browser does not have scroll bars. A. 1. These items can include stock controls. For information. table cells contain more content than their frame can hold. For information about these properties. see Data binding for coach views. if you double-click a coach view instance in the layout.Defining the contents of coach views You can define what a coach view displays to users at runtime. click . . see Responsive settings for coach views. Process Designer automatically selects it and shows its properties. For examples of how you can create your own controls as coach views. 3. When you drop a coach view onto the layout. . Each item that you drop on the layout is a separate instance and changing its properties does not affect the properties of other instances. The list contains the variables that you defined in the Variables page that have the same type as the type of the data binding that is defined for the coach view. for example. the list contains the view definitions with a data type that matches the type that is defined for the data binding. to create a two-column arrangement. Define the general properties of the coach view instance. Set the type of device you are creating the layout for. variables.Bind it to data such as a business object or one of its parameters by selecting the data from the list. drop items from the palette or from the library. see Example: creating a Dojo button control and Example: creating a jQuery button control. Procedure Add coach views and other palette and library items to the coach view in its Layout page. you drop two instances of a Button stock control.Tip: You can nest the sections.Change its label to more appropriate text. For example. For example. 2. For example. B. Without scroll bars. However. Remember: Consider the effect of the various browsers when you are defining the layout and what you must do to handle their differences. you are changing the definition of the coach view. These changes affect all existing and future instances of that coach view. including setting the following properties: . If the type of your selection and the type of coach view data binding do not match. the coach view opens in the editor. On the layout. Use horizontal sections and vertical sections to arrange the items. drop two vertical sections in a horizontal section. see Coach view general properties. If you choose to select an existing view definition. define its properties. it might not be obvious when.Change the view definition that it uses. Click Select and then select the 637 . Changing the name of one does not affect the other. For information about dropping variables and the data binding that occurs.To set a configuration property to a variable. If you then edit the coach view. To expose a configuration property. you have a Text stock control that you want to contain only five numbers. in your coach view. For information. Exposing the configuration property automatically creates a configuration option as a variable in the current view. Coaches or coach views that contain your coach view can then set these labels to something appropriate for that coach or coach view. see Coach view general properties. If you are setting the string through a variable. For information. . type \d{5} . the variable is a string with a value of "\\d{5}". The list contains the variables with a data type that matches the type that is defined for the configuration option. do not surround the string with quotation marks. The configuration option has data binding that matches what is defined in the selected coach view. If you assign the validation to a variable. click its button. see Positioning options for coach view instances D. For information and an example of adding a class to change the position of a text box label. you enter. If you enter the validation string. If you are setting the string by entering it directly into a configuration property. Optional: To override existing styles on the instance. set its visibility property.Setting the visibility of coach views To allow or prevent users from seeing or editing a coach view. see Coach view general properties. Important: The designer handles strings that are directly set in a configuration property differently from strings that are set through a variable. C. As an alternative. add HTML attributes and classes to it. the regular expression to use to evaluate the contents of the Text stock control.Adding bidirectional language support IBM® Business Process Manager can support languages that are written from right to left and languages that are written from left to right. Set the height and width of the coach view instance and set how much padding you want around it by setting its style properties. Parent topic:Developing reusable coach views Related information: Adding variables to coach views Providing information about coach views Defining coach view behavior 638 . For example.variable from the list. In this field. see Setting the visibility of coach views. For example. . surround the string with quotation marks and use escape characters where necessary. you can expose certain configuration properties to the coach views or coaches that contain your coach view. Set how the parent coach or coach view displays the coach view instance. The Text stock control has the Validation field. you add a check box as a set of radio buttons and expose its True Label and False Label configuration properties. For information about the visibility values. E. as a string. IBM Business Process Manager uses left to right as its text direction. Procedure 1. However. About this task By default. set the Base Text Direction property to one of the following values: Value Default Contextual Left to Right Right to Left Description Inherit the text direction that is set in the user's profile. Display the text from right to left no matter what characters are in the text. In this case. you can have a coach with fields with English text that is going from left to right and fields with Arabic text that is going from right to left. use the CoachViewRTL class in your CSS rules. Optional: To provide customized styling for bidirectional languages. When the coach is generated for a bidi language. Display the text from left to right no matter what characters are in the text. In the General properties of a coach view. Set the name of the attribute to dir and the value to ltr or rtl. if the first strong directional character is from a right to left language. 639 . The Base Text Direction property is not available until you enable it as a preference of Process Designer. For example. Display the text according to the first strong directional character in the string. For example. it contains a tag like the following example:<body dir="rtl" class="CoachViewRTL"> 4. This applies to all text elements that a Coach View displays. 3. a Text stock control has an Arabic label but its contents are English. Using the steps that are contained in Setting preferences. 2. add an attribute to its HTML attribute properties. display the text from right to left. Optional: To support UI mirroring that is opposite to the default directional setting of the current locale. by using this property.Adding bidirectional language support IBM® Business Process Manager can support languages that are written from right to left and languages that are written from left to right. click the Capabilities > IBM BPM Advanced Features > Base Text Direction option. Any coach views contained by this coach view inherit this attribute. you can reverse this direction for any coach view by using its Base Text Direction general property. For example. the text in the label is right to left while the text in the field is left to right. What to do next Implementing mirroring and bidirectional text for a coach or composite coach view is an iterative activity. You might have to repeat steps 2 to 4 each of the children coach views until you achieve the look that you want. Parent topic:Defining the contents of coach views 640 . None Additionally.Read only . For information about these options and visibility in general.Hidden . you can set the coach view to inherit its visibility from the coach or coach view that contains it. Same as parent is the default value. For example.Setting the visibility of coach views To allow or prevent users from seeing or editing a coach view. You do this by setting the visibility of the your coach view to Same as parent.Editable . The contents of the Visibility page differs depending on whether the coach view is within a coach or a coach view. your coach view is within a coach view that has Read only visibility. coach views are visible and editable. Within a coach Within a coach view 641 . If your coach view is set to Same as parent visibility. you can change the following options on the Visibility page of the coach view.Required . . see Coach view visibility properties. However. set its visibility property. your coach view inherits the Read only value. About this task By default. only the first option Generally. rule. Restriction: You cannot have different rules or scripts for each screen size setting. you would set the visibility to Editable when you are editing the large screen layout. In the procedure. setting the visibility by value is applies. set its visibility in one of the following ways: Option Description 642 . If you do not specify a value for the small screen layout. it inherits the visibility value from the medium screen layout. You then switch to the medium screen layout and change the visibility to Hidden or None.For a coach view that is in the layout of a For a coach view that is in the layout of a coach. For information. the simplest but least flexible option while setting the visibility by script is the most complex but most flexible option. To do this. you might want to have a coach view visible in a large screen but hide it for a medium or small screen. you can set the visibility of coach view according to a value. Procedure In the Visibility properties of a coach view. You can also change the visibility according to the screen size if you chose to set visibility by value. you can set the visibility of the coach view. see Responsive settings for coach views. or the coach view according only to a value. script. For example. and then select the variable that determines the visibility of the coach view. first select the view in the Invisible Items section of the palette. then configure the view properties. 643 . You can optionally set a different value for different screen size settings by selecting the screen size setting first. it does not display on the canvas. If you want to set the properties of a hidden view. Note: If you set the visibility of a view to Hidden or None.By value Select Value and then either select a value from the list or click . then selecting the visibility value for that screen size setting. The rules have an OR relationship.Determine whether the first rule in the rule set is based on a variable value or on a team membership and select Variable or Team accordingly. For a team.For condition. the format of the rule is visibilitymembershipteam.For team.For variable. To create a visibility rule that is based on a variable value. enter the variable value that triggers the application of the visibility value.Create the first rule in the rule set. A visibility rule set has one or more rules and a default value for when no rule applies. Subsequent clicks add a variable value or team membership for each click. For a variable. complete the following steps:For visibility. select the type of comparison that is used on the variable value. set the value for the visibility in the Set to field. 644 . click Select and then select the variable that is defined in the human service that determines when the visibility value applies. To create a visibility rule that is based on team membership. click . Place the rules in the order of their applicability because the coach view uses the visibility value of the first rule that applies. complete the following steps:For visibility. To add more variable values or team memberships to a rule.Set the default value for the rule set by selecting a value in the Otherwise field. the format of the rule is visibilityvariableconditionvalue.For membership. select the team that the user belongs to. set the value for the visibility in the Set to field. If there are multiple variables or team memberships in a rule.For value.By rule Select Rule and then create a visibility rule set. select the membership type of the user in the team. member.By script each of them has an AND relationship with the other.get("drink") == "Tea") { if(context. Users from the sales team can edit the coach view. That is. The following parameters are available for your code: In your JavaScript. } else { return "READONLY". } } else { return "NONE". you might want the user interface to display a coach view when the user selects tea from the MyDrink brand. When a user changes the value in one of these watched variables. each return value must be a string with one of the following values: REQUIREDEDITABLEREADONLYNON EDEFAULTHIDDEN. Type JavaScript code into the field. Create more rules as needed. } Parent topic:Defining the contents of coach views Related information: The coach view context object Building coaches Developing reusable coach views 645 .Select one or more local variables that trigger the script to run. Select Script and then create a visibility script:Click Select. all of them must be true for the rule to apply. The service has Drink and Brand variables. the resulting change event causes the script to run.get("brand") == "MyDrink" && local.team.indexOf("SalesTeam") != 1) { return "EDITABLE". You select these variables and then add the following code into the field: if(local.bpm. For example. As such. (function) A callback function when the service call returns successfully.Calling Ajax services from coach views You can invoke Ajax services from within coach views. B. The default service is the application programming interface (API) for which custom services must match. The Coach framework calls Ajax services using the BPM REST API in taskless mode.options. the object must be JSON serializable. Use the following guidelines for your event handler code. Implement the Ajax service. (The names and types of both inputs and outputs must match. Select the Service type option.Note: The default service can optionally be overridden with a compatible service by users of this coach view. About this task To call an Ajax service in a coach view. Optional properties for args JavaScript object Property params Description (String or Object) A JSON string that represents the input to the service.Use: this. The Data section opens. the Ajax service should already be built. Procedure 1. The callback function has a single parameter containing the output(s) of the service call. 2. If an object is provided.Invoking the service using a JavaScript call syntax: .stringify().<service_option_name>(args)Table 1. select a method (load. In the Variables tab. view. change.) You can implement the Ajax service using either a simple JavaScript call syntax or a REST API.In the Behavior tab under Event Handlers. it will be serialized into JSON format using JSON. click the plus sign next to Configuration Options. An Ajax service can be invoked by a simple JavaScript call syntax or by a REST API. unload. or collaboration) and then provide code for calling the Ajax service. you must specify configuration options of type Service in the coach view variable declarations and select an Ajax service as a default service to be used. . Open a coach view and then specify a Service type configuration option in the variable declarations. select the default service. A.context. and then provide a name to represent this configuration option service. Before you begin Before you begin. load 646 . context.path). headers.binding. e). data)."className":"PlacedPosition"}}}. Restriction: If the Ajax service uses an error end event with error code and error data. error: function(e) {console.error (function) A callback function when the service call results in error.log("service call failed: ". The callback function has a single parameter containing the error information."Room":"101". the data object that you get from the response contains a property holding the metadata of your object. style:"margin:5px 0px"}.service_option_name.get("value")}. load."key":"@54".bookPlacedPosition).stringify(input). domConstruct.set("BookPlacedPosition".Use: this. _this. }."data": {"bookPlacedPosition":{"Floor":1.context."Row":2. the @metadata object is added in your structure: this.Invoke the URL using an XHR call and specify the following properties appropriately: handleAs.create("img". function(url) { var relPath = new url(data. var input = {text: this. Tip: If the Ajax service output is a complex-type business object.options.Serialize your input data in JSON format and add it to the URL using params as the parameter name. Note: The service is invoked only using JSON input and output. error properties. sync.log("service returned: ".context. load: function(data) { console."shared":false.path. // now dynamically create the img tag require(["dojo/_base/url"]."@metadata": {"dirty":true.data. 647 . "first").c30905ba-8d17-41f4b2a8-08cbb6516ff0T". }). ."rootVersionContextID":"2064."step":"End". {src:relPath.<service_option_name>. for example: {"status":"200". var serviceArgs = { params: JSON.} } this.context.options.context. The error message returned contains the error code but no error data.Invoking the service using a REST API: .url (This contains the URL of the Ajax service."data":{"serviceStatus":"end".get("value"). ."actions":null}} If you directly set the response object to your binding like the following example.) . Example The following example is JavaScript code for a load event handler:var _this = this.element. the content of the modeled error in the Ajax service is not available in either the JavaScript error property or in the REST API error property.options.Ajax_service_name(serviceArgs). To avoid an exception.binding. _this. Parent topic:Developing reusable coach views Related information: Example: wiring coaches in a heritage human service Stock controls 648 .data.When you trigger the boundary event to the server.bookPlacedPosition).context. for example:delete data.bookPlacedPosition['@metadata']. remove the @metadata object from the response before you set it to the binding. the server throws an exception because it does not expect the boundary event to have the @metadata object.set("BookPlacedPosition".get("value"). png. Must be one of the following: com_ibm_bpm_coach.assetTyp e_WEB: web managed asset (css. To access these assets from a coach.assetTyp e_SERVER: server managed asset (for example zip. If assetType is not one of the three allowed (see the following table).com_ibm_bpm_coach. For example. returnWithoutAssetName) .zip!path/file. style sheets.returns .zip file.getManagedAssetUrl = function(assetName. 2.Generating URLs of managed assets Managed assets are images. use the following format for the URL: file. but are developed outside of Process Designer. if you are pointing to an image file in a . Use the following parameters: Parameter assetName (String) assetType (String) Description The file name of the managed asset. AMD modules or other assets that are part of a coach view.syntax . For example. .extension.getManagedAssetUrl global JavaScript function composes the URL to the managed assets without checking whether the asset exist or not. Procedure 1. Use the following syntax: .the URL of the managed asset. to generate a URL for an AMD module which is contained in a zip file.) com_ibm_bpm_coach. assetType. About this task The com_ibm_bpm_coach.Note: You can use the '!' notation to reference a file inside an archive. the function returns null.. you might need use a global JavaScript function to generate the URL of the asset.assetTyp e_DESIGN: design managed asset (xsl) 649 . jar) com_ibm_bpm_coach. projectShortName. The type of the managed asset. projectShortName (String) returnWithoutAssetName (Boolean) The short name of the project where the managed asset is requested. Indicates whether the return url should include the asset name. you must include the PROJECT parameter to ensure that the Coach View can use module in the context of the process application. If this is not provided. Optional. the default is false. Parent topic:Developing reusable coach views 650 . If the module is in a referenced toolkit. the current project is assumed. and the asset name is included in the url path. If this parameter is not provided. You can create your element using custom HTML. Procedure To generate a unique ID: . By using $$viewDOMID$$ in your coach view implementation. and assign the DOM ID attribute by prefixing with $$viewDOMID$$. multiple instances of the same coach views could be used in a single coach. At run time. you can ensure that all of your DOM elements have DOM IDs that are globally unique. However. . during collaboration the default highlighting behavior is implemented based on a unique DOM ID. for example $$viewDOMID$$_buttonDiv.Open the coach view .Switch to the Layout page . To ensure a unique ID. As a result. the $$viewDOMID$$ attribute will be replaced by a unique ID (the DOM ID of your coach view) for the element.Generating a unique ID for a coach view In some situations you might want to use the ID attribute for your DOM elements within a coach view. unique DOM IDs are generated for all coach views automatically. and use $$viewDOMID$$ in the id attribute: <div id="$$viewDOMID$$_myId1"> <span id="$$viewDOMID$$_myId2"></span> <input id="$$viewDOMID$$_myId3" type="button" class="Jquerybutton" name="jbtnName" value="default"></input> </div> Tip: To avoid potential conflicts. About this task Because coach views are reusable. you might want to highlight an element such as a button at run time. all DOM IDs must be globally unique. For example. When the view is rendered.Create a custom HTML control. this keyword will be replaced by the coach view DOM ID. For example. Parent topic:Developing reusable coach views Related information: Accessing a child coach view by using a control ID 651 . you can use the $$viewDOMID$$ placeholder keyword.Enter custom HTML code. use a meaningful suffix after $$viewDOMID$$. Click Debug in the upper-right corner. 2. You can see the generated page for the coach. The Internet Explorer Debugger tool stops at a debugger statement at the beginning of the coach initialization. 3. then click Step Into begin debugging the coach. The Internet Explorer Debugger tool stops at a debugger statement at the beginning of the coach initialization. 2. 4. then click Step Into begin debugging the coach. click Step Over to move to the coach that you want to test. Open the Google Chrome Developer tools. Continue normal JavaScript debugging in the Internet Explorer Debugger tool. Google Chrome 1. you need to use the debugging features of your browser along with the debugging features of the Inspector view in IBM Process Designer. pausing on the first step of the client-side human service after the Start event. 6. In the Inspector. click again in the Inspector. The Inspector opens. Continue normal JavaScript debugging in the Internet Explorer Debugger tool. click Step Over to move to the coach that you want to test. 5. 2. Open the Developer tools from the tool bar or by pressing F12 and go to the Script tool. In the Inspector." You can ignore this error. then click Step Into begin debugging the coach. Click Start debugging. 3. Open the Developer tools from the tool bar or by pressing F12 and go to the Debugger tool. 5.Tips for debugging coach view lifecycle method inside client-side human services To debug your coach views inside a client-side human service. click Step Over to move to the coach that you want to test. You can see the generated page for the coach. follow the browser-specific tips to add breakpoints and debug the lifecycle method for your coach views. 2. To resume debugging. Locate the coach view lifecycle method code and set breakpoints as required. Internet Explorer 9 and 10 1. Open the client-side human service that contains the coach that uses the coach views you want to debug. Note: Internet Explorer will refresh the window which might generate an error in the client-side human service that reads "SCRIPT5022:This deferred has already been resolved. In the Inspector. 4. Locate the coach view lifecycle method code and set breakpoints as required. Internet Explorer 11 1. When the client-side human service playback window launches. 3. 1. 652 . 4. Locate the coach view lifecycle method code and set breakpoints as required. Mozilla Firefox 1. 4. click again in the Inspector to restart the debugging process. If this occurs. 3. then close and re-open the browser debugger. click Step Over to move to the coach that you want to test. Parent topic:Creating user interfaces for business processes Related information: Tips for debugging coach views in Process Portal 653 . Note: You might encounter an issue where Firefox Debugger does not display the generated page for your coach. Continue normal JavaScript debugging in the Firefox Debugger tool. This causes the Chrome debugger to refresh and properly display the generated page for the first coach. Note: You might encounter an issue where Chrome Debugger does not display the generated page for the first coach in a client-side human service. Continue normal JavaScript debugging in the Chrome Debugger tool. The Firefox Debugger tool stops at a debugger statement at the beginning of the coach initialization. In the Inspector. The Google Chrome Debugger tool stops at a debugger statement at the beginning of the coach initialization. Open the Firefox Debugger. click Click to resume in the Firefox Debugger tab. 5. If this occurs. wait until the coach is loaded. You can see the generated page for the coach. 2. Locate the coach view lifecycle method code and set breakpoints as required. click Resume script execution in the Sources tab.3. then right-click on the playback window and select This Frame > Reload Frame to reload the coach iFrame. 5. Next. then click Step Into begin debugging the coach. You can see the generated page for the coach. Open the Developer tools from the tool bar or by pressing F12 and go to the Debugger tool. Locate the coach view lifecycle method code and set breakpoints as required. In Process Portal. Login to Process Portal. 3. 4. 2. You can see the generated page for the coach. Login to Process Portal. See Enabling tracing for Coaches. In Process Portal. Before you begin Before you start debugging your coach views. Locate the coach view lifecycle method code and set breakpoints as required. Continue normal JavaScript debugging in the Internet Explorer Debugger tool. 2. Open the Google Chrome Developer tools. The Internet Explorer Debugger tool stops at a debugger statement at the beginning of the coach initialization. You can see the generated page for the coach. you must enable JavaScript debugging in IBM Process Portal. The Google Chrome Debugger tool stops at a debugger statement at the beginning of the coach initialization. Internet Explorer 11 1. You can see the generated page for the coach. 6. 4.Tips for debugging coach views in Process Portal You can debug the lifecycle method for your coach views in IBM Process Portal. Google Chrome 1. Open the Developer tools from the tool bar or by pressing F12 and go to the Script tool. 2. 7. Use the coach view debugging tips that correspond to your chosen browser. launch the client-side human service or BPD that contains the coach view that you want to test. launch the client-side human service or BPD that contains the coach view that you want to test. The Internet Explorer Debugger tool stops at a debugger statement at the beginning of the coach initialization. Note: You might encounter an issue where Chrome Debugger does not display the generated page for the first coach in a client-side human service. If 654 . In Process Portal. Internet Explorer 9 and 10 1. 4. 5. 5. Login to Process Portal. 6. Continue normal JavaScript debugging in the Internet Explorer Debugger tool. Click Start debugging. 3. You should also ensure that the client-side human service containing the coach views that you want to test is either exposed as a startable service or is contained in a BPD which is exposed to start in the Process Portal. 3. launch the client-side human service or BPD that contains the coach view that you want to test. Note: You might encounter an issue where Firefox Debugger does not display the generated page for your coach. Mozilla Firefox 1. 5. 5. Continue normal JavaScript debugging in the Chrome Debugger tool. 3. 4. You can see the generated page for the coach. Parent topic:Creating user interfaces for business processes Related information: Tips for debugging coach view lifecycle method inside Human Services 655 . Locate the coach view lifecycle method code and set breakpoints as required. wait until the coach is loaded. and then close and re-open the browser debugger. 6. Open the Firefox Debugger. 2. This causes the Chrome debugger to refresh and properly display the generated page for the first coach. The Firefox Debugger tool stops at a debugger statement at the beginning of the coach initialization. re-launch the client-side human service or the task in the BPD from Process Portal. then right-click on the coach and select This Frame > Reload Frame to reload the coach iFrame. Next. launch the client-side human service or BPD that contains the coach view that you want to test. click Resume script execution in the Chrome debugger Sources tab. Login to Process Portal. click Click to resume in the Debugger tab. Continue normal JavaScript debugging in the Firefox Debugger tool. Locate the coach view lifecycle method code and set breakpoints as required.this occurs. 6. If this occurs. In Process Portal. and then click OK. 4. 3.Enabling JavaScript debugging for coaches For debugging purposes. click Custom properties. Results You can see the uncompressed and readable Dojo and Coach framework JavaScript in your browser debugger. However. Save your changes to the master configuration. Click isDebug. When you set IBM Business Process Manager to use the readable Dojo and the Coach framework JavaScript. 6. Restart the application server instance. Parent topic:Creating user interfaces for business processes Related information: Building coaches Developing reusable coach views 656 . Under Additional Properties. Before you begin JavaScript debugging must be configured on the application server instance where IBM® Business Process Manager is installed. 5. Procedure 1. The list of custom properties opens. you can set your coaches and coach views to use the readable versions of Dojo and the Coach framework JavaScript. click Mashups_ConfigService. On the Resource environment providers page. Open the administrative console and click Resources > Resource Environment > Resource Environment Provider 2. change the Value field to true. it uses the uncompressed version of these files. About this task IBM Business Process Manager normally uses the compressed version of Dojo and the Coach framework files. the files in these versions are not readable. they might try to access these resources. Define the myChange event handler in the coach view JavaScript. you have a coach view. . and you register event listeners for your coach view in its load event handler.context is null message This message can occur when registered event listeners are not unregistered. The unload event handler releases the resources used by the coach view.bindAll(this. 3. This step is necessary because the previous binding subscriptions are lost when the complex object is replaced. viewScope. 2.myChange.Create a callback to capture changes to the complex object: 1. Bind the variable as a configuration option to the coach view.Create a flag to indicate that the complex object has changed: 1. see Enabling tracing for Coaches. The change in the configuration option variable invokes the change event handler for the coach view. this). For example.get("value"). Add server-side scripting that updates the variable when the complex object changes. 2. Parent topic:Creating user interfaces for business processes 657 .context. For more help troubleshooting coaches. Add a variable of a simple type such as Boolean or String to the human service. To make your coach view aware of changes to a complex object. call bindAll() to rebind to the properties. If you do not unregister the event listeners. which causes the viewScope. Add the logic to handle properties changes. An example of a complex object is a business object. In the load event handler of the coach view. 4. In the change event handler.binding.Coach and coach view troubleshooting The following sections list issues that you might encounter and information about possible solutions. 3. Coach views that are bound to re-initialized complex objects might contain old data Coach views that are bound to complex objects might not refresh data when the runtime flow returns to a coach that contains these coach views.context is null message. use one of the following techniques: . Add code to handle the changes in the complex object. add the following code: this. If you set the responsive settings for a coach view instance for the medium screen size. Typically. all three screen sizes use the same value for the setting and the coach view instance appears the same in all user environments. you can configure the responsive settings for all the coach view instances in your coach or coach view by using one screen size. and do not provide values for the medium or small screen sizes.Responsive settings for coach views At run time. and small. Screen size settings Screen size setting Small Medium Large (default) Icon Width 640 pixels or less 641 . Table 1. You can configure these settings separately for different screen sizes so that you can design one interface that changes in appearance and behavior based on the user's screen size. the pixel count of the viewport width determines which screen-size setting the device browser uses to display the coach and the coach views that it contains. then the large screen values apply in all user environments. For example. Screen size is set in the upper-right corner of the coach or coach view canvas. 658 . Websites such as http://viewportsizes. As you change the screen size. the browser could have one screen size for the portrait orientation and a different screen size for the landscape orientation. The web browser viewport is often smaller. If a device has an unusual size. Prerequisite: Responsive options are available only when you are authoring in the Process Designer web editor. Note that the viewport pixel counts for a web browser on a device do not necessarily match the advertised pixel counts of the device screen.1024 pixels More than 1024 pixels When you build your coach or coach view. The large screen size is the default. the device browser uses the same screensize setting regardless of the device orientation. if you set values for the coach view instance margins for the large screen size.com are useful for determining the viewport size for a particular device. users can interact with your application interfaces by using a range of devices. At run time. medium. the medium screen size values apply in small screen size environments. each of which have their own characteristics. depending on the widths of the two orientations. such as screen size and standard user-interface conventions. You can then configure the same settings using different values for another screen size. The three screen size options are large. the available canvas area changes to reflect the screen size in the runtime environment. but do not provide values for the small screen size. You can build interfaces that are responsive to the user's runtime environment by specifying the responsive coach view settings. however. If you do not provide different values for a responsive setting that is available for a coach view instance. can also be set relative to a particular device size. For information about how to set configuration properties as responsive. you might create a coach view with a configuration option that determines whether selection controls on an instance of that coach view are rendered as check boxes. see Coach view visibility properties. Positioning properties enable you to configure the placement and spacing of a coach view instance. to pare down the user interface in the smallest screen-size environments. Configuration options. You can also add responsive configuration options to your own coach views. If this configuration option is marked as responsive. see Configuration properties and configuration options. can change the presentation or even the contents of a coach view instance. see Positioning options for coach view instances. it can have three different settings corresponding to three different screen size settings. and visibility properties. For information about how to set responsive positioning properties. visible. For example. or slider controls. Visibility properties. which determine whether a view is hidden. when they are marked as responsive. For information about how to set responsive visibility properties. so that coach content can be spaced more closely together when the interface is displayed on smaller devices. configuration options. radio buttons. for example. For example. you might hide a more detailed coach view instance in small screen size environments and show a simplified version instead. You can set positioning properties for each screen size. Parent topic:Creating user interfaces for business processes Related information: Defining the contents of coach views Configuration properties and configuration options 659 . editable.Responsive settings for coach view instances You can configure the following types of properties for different screen sizes: positioning properties. depending on the device. and so on. For more examples and for sample code. . . . understanding how to build coaches that call them and use their data can be useful to anyone building a heritage human service or a business process. see the Sample Exchange. . . Parent topic:Creating user interfaces for business processes 660 .Example: creating a Dojo button control This example shows how you can use the Dojo library to implement a coach view.Example: creating a coach for tablets and smartphones This example shows how to create a coach that changes how it displays its contents according whether users see it in a desktop browser. such as jQuery.Example: creating a Select control using custom HTML This example shows how you can use scripts to bind selected values in a Custom HTML control to the business data of a coach view. . It then shows how to make the coach view available as a template. . when creating a coach view. .Example: validating a coach in a heritage human service This example shows you how to validate the data in a coach within a heritage human service.Example: creating a template This example shows how to create a coach view that contains a simple header and footer.Example: creating a jQuery button control This example shows how you can use an external third party library.Example: showing the label of a complex coach view This example shows how to show the label of a complex coach view in the coach or coach view that contains it. or on a smartphone. .Coach and coach view examples This documentation includes a number of examples that demonstrate how to create and code the various parts of coaches and coach views. .Example: validating a coach in a client-side human service This example shows you how to validate the data in a coach within a client-side human service using client-side validation. on a tablet.Example: creating a tabbed coach This example shows how to create a coach that contains three tabbed pages. Since Ajax services are a common form of service. .Example: creating a coach that calls an Ajax service You can quickly build coaches that call Ajax services and display data from those services.Example: wiring coaches in a human service This example shows how you can wire a coach for a food service company to look up suppliers. This example creates a coach view called My Template. Add the image file as a web file. My Template has three areas: a header that contains standard text.Example: creating a template This example shows how to create a coach view that contains a simple header and footer. The content box is a placeholder for content that is defined by coach views and coaches that users create based on the My Template coach view. It then shows how to make the coach view available as a template. add the following HTML code as text that goes in the header: <div id="header"> <h1 id="header_text">My Company</h1> </div> <div id="content"> This code defines the text that goes in the header division and opens the main content division. C. a content area. Define the layout of the My Template coach view: A. and a footer that contains some more standard text. Click the Add icon for User Interface and then select Coach View. 3. B. Create the My Template coach view. content placed in the content box fits between the header and footer in the My Template coach view. In the properties of the custom HTML item. Drop a content box below the custom HTML item for the content area. 1. drop a custom HTML item onto the layout canvas. Click the Add icon for Files and then select Web File. Upload the image for the header background: A. use this image file: 2. In the Layout page of the coach view. 661 . B. For the example. In this case. Create the My Template coach view: A. To separate the areas. My Template uses <div> tags. B. } #content { background: #F8F8F8. height: 60px. } #header_text { color:black. padding: 10px 0 10px 0. } #footer_text { color:black. drop a custom HTML item onto the layout canvas below the content box. border:none. text-align: right. The layout of the My Template coach view looks like the following screen capture: 4. In the Behavior page. font-size:40px. background-size: 100% 100%.gif'). border:none. background-repeat: no-repeat. define the look of the My Template coach view by adding the following code as inline CSS:#header { text-align: center. background-image: url('banner. E. In the properties of the second custom HTML item. } #footer { padding: 5px 25px 5px 5px. background: #EAD6D1. font-size:12px. 662 .</div> <div id="footer"> <h2 id="footer_text"> My Company</h2> </div> This code closes the content division and defines the text that goes in the footer division. add the following HTML code as text that goes in the footer.D. In the Layout page of the coach view. zip file as a web file.css file and any images it refers to in a . To make the My Template coach view into a template. in the Overview page select Use as a Template. 5.zip file means that the system can find the referenced image files.zip file. Save the My Template coach view.css file and then use Included Scripts to refer to the file. put your . If you use this approach.png file. use the following format for the URL:url('zip_name. 6.zip file. To represent the My Template coach view on the palette and in the New Coach View wizard. } If the image has been packaged in a . Putting all of the files in the . you can now base it on the My Template coach view. 7. save it as a . Parent topic:Coach and coach view examples 663 .gif'). Tip: You can also put the CSS code in a .zip!path/banner. and use that file as the palette icon. It also has an area between the two where you can drop content. Then add the . When you create a coach view or coach. The new coach view or coach now has the header and footer. add a palette icon. Tip: Take a screen capture of the My Template coach view in a browser.padding: 20px. Example: wiring coaches in a human service This example shows how you can wire a coach for a food service company to look up suppliers. the human service might have an execution error when the coach is submitted.supplier. an Ajax service. Any coach view that fires a boundary event that is added to a coach can be selected as a boundary event and wired as such in the sequence flow.local.Create the example artifacts listed in section Example artifacts. you can initialize your variables before looping back to the coach. } .If you have a quoteApprovers variable and use a client-side human service. In the Variables tab. If the logic that is executed before control is returned to the coach. When you wire a coach to loop back to the same coach.quoteApprovers = new tw. .Create a coach that is made up of a coach view and two buttons. Boundary events are specified using the Can Fire a Boundary Event setting in the Overview tab of a coach view. (This includes business data objects. use this code in a client-side script before returning to the coach:if(!tw. and a human service.toolkit. This example shows how to configure a coach to loop back and to proceed to the end of the service. add a coach to the canvas. 2. such as in a lookup service.IBM.If you have a quoteApprovers variable and use a heritage human service. The Button stock control fires a boundary event by default. a coach must contain a coach view that contains a control that fires a boundary event. In the Diagram tab. A.Tip: Initialization of data is necessary when a coach loops back to itself after executing logic such as a script task.object.Configure the human service diagram components and sequence flow.) Overview of tasks in this example: . To create a wire connection from a coach in a human service diagram.listOf.quoteApprovers = {}. drag a coach onto the canvas and name 664 . and the logic causes a property or variable to be uninitialized (equal to null). .local.local.Add input and output variables to a human service.quoteApprovers) { tw. use this code in a server script before returning to the coach: if(!tw. a coach view.quoteApprovers) { tw. To ensure that such execution errors do not occur. add the following local variable for both input and output: .If you use a heritage human service. This provides a faster user experience. } Prerequisite tasks for this example: . for the Variable Type.local. Creating the Submit Supplier coach.Employee(). For example: . select the Supplier business object. Open the Supplier Form human service and complete the following steps: 1. the data displayed on the page is refreshed at run time without redrawing the entire page. . B. Table 1.local. anyState". F. select the coach that was generated for you and name it Submit Supplier. A. anyCity.Name = "John's Restaurant". For the End State Binding. Select the line going from the Submit Supplier coach to the Supplier Lookup script. A separate web browser window opens showing your coach. The human service is complete. select the coach and drag a vertical section onto the canvas. 4. C.it Submit Supplier.supplier. accept the default settings. The view properties open. select the supplier input variable (created in step 1). Business data objects Name Parameters 665 . G. } else if (tw. . drag the Supplier Information view onto the canvas. B. To end the process. Connect the Submit Customer coach to the End Event component and then select the connecting line.address = "1 anyStreet.ID == "1234") { tw. In the diagram. type either 1234 or 2345 and then click Supplier Lookup. Example artifacts Create the artifacts listed in the following tables before you begin the example. From the palette.supplier. The line properties open. drag a Script component onto the canvas and name it Supplier Lookup.address = "2 anyStreet. click Submit. The line properties open. 3. } C. From the palette (under No Tags). D.supplier. Save changes. B. E. If you use a heritage human service. 5. provide a script for the supplier lookup feature that is similar to the following example:if (tw. In the Coaches tab. In the Implementation properties. The corresponding supplier name and address data is returned. D.If you use a client-side human service. drag the Button control into the vertical section and name it Supplier Lookup. In the ID field.local. A. tw.local.supplier. the Supplier Lookup script is a client-side script.local. Finally connect the script back to the Submit Supplier coach to create a loop. Select the OK button that was previously generated and name it Submit.supplier. click Select and then select the Submit button (created in step 2). click Select and then select the Supplier Lookup button (created in step 3).supplier.Name = "Jane's Bakery". If you use a clientside human service. In the Diagram tab. and then run the service. connect the Start Event component to the Submit Supplier coach. anyState".Tip: For properties that are not specified. the Supplier Lookup script is a server script. E.local.ID == "2345") { tw. Configure the Supplier Lookup script and sequence flow. Then connect the Submit Supplier coach to the Supplier Lookup script. Test the features in your application. F. tw. For the Binding. For the End State Binding. anyCity.local. similar to:tw. Human service Name Supplier Form Properties Configure the human service using the steps in this example. } else if (tw.text.java.charAt(0) == '2') { tw.results[0] = "2345".local.results = new tw. Packages.results[0] = "1234". if (tw. } else {/* */ } Table 3.System.Supplier ID (String) Name (String) Address (String) Table 2.IDEnable Autocompletion: OnAutocompletion Service: Supplier ID Lookup (Ajax service)Name properties:Binding: Supplier.flush(). Coach views Name Supplier Information Contents Text controls: Supplier ID.out.local.NameAddress properties: Binding: Supplier. and AddressSupplier ID propertiesBinding: Supplier.String().local.out.text: " + tw.text.lang. Parent topic:Coach and coach view examples 666 .text).local.charAt(0) == '1') { tw. Packages. Ajax service Name Supplier ID Lookup Contents Script component with added script for the lookup feature.println("tw.local .local.lang.Address Table 4.local.System.listOf. Name.java.object. Example: creating a tabbed coach This example shows how to create a coach that contains three tabbed pages. You use a coach view to add the fields to the page. The third page contains a table of addresses. Normally. the tab control is a good choice. In this case. you would relabel the text fields to something more appropriate for your users. In this example. The first tabbed page of the coach contains three text fields that have some general information about a customer. The second page contains a set of phone numbers. you add the fields directly to the coach using sections to set the page layout. In this example. the coach view you add 667 . you have a Customer business object that contains many properties. but this example will retain the default labels to concentrate on laying out tabbed pages and mapping data to text fields. To capture or display all of these properties within a single coach. In its Variables page. see Creating custom business objects in Process Designer. With the Customer business object. Note:To perform this task. . work(String).Address is a business object that has number(String). add the PhoneNumber business object as the business data variable named phoneNumber. . and city(String) parameters. 2. so ensure that you select Is List for it. and lastName(String) parameters. For information about creating business objects. addresses is an array of the Address type. and cell(String) parameters. Create the Customer business object. street(String). which results in a table.PhoneNumber is a business object that has home(String). you must be in the IBM® Process Designer desktop editor. and cell parameter variables onto the layout. A text control is added to the layout for each variable because it is 668 . In the Layout page. firstName(String). It also has two complex parameters: phoneNumbers(PhoneNumber) and addresses(Address). 1. C. Customer has id(String).to the page is a list. Create the PhoneNumberView coach view. drag the home. work. B. Create the coach view for the PhoneNumber business object: A. rename the coach to Customer Coach. In the Variables page. drag a tabs stock control onto the Customer coach layout. Create a heritage human service named Customer Human Service. add the Customer business object as a private variable. 669 . 6. Open its diagram and drag a coach onto the diagram. 4. 5.the coach view associated with the String type. The tabs control is in the Section category of the palette. 3. In the Step properties. In the Coaches page. you can then add as many elements as you want into that section. Rename the section to General. Drag a vertical section onto the tab control. change the label of the PhoneNumberView instance to Phone Numbers. Create the Phone Numbers page: A. The name that you see on the tab comes from the label of the section. Drag the PhoneNumberView coach view onto the tab control. Bind the PhoneNumberView coach view to the customer. A tabbed page can contain only one element directly. Create the General page: A. B. and lastName variables are parameters of the Customer variable. You can see a PhoneNumberView 1 tab in the tab control.7. If you did not add a tag to the coach view. 8. In the General properties. D. Select the tab. E.phoneNumber variable. This action means that any data users enter into the fields gets set in the variable for the heritage human service. Drag the firstName and lastName variables onto the horizontal section. 670 . firstName. you can find it in the NoTags category on the palette. D. Drag the id variable onto the vertical section. Drag a horizontal section onto the vertical section below the id text control. By adding the section. B. C. The id. C. 10. Create the Addresses page: A. In the Configuration properties. change the label of the table to Addresses. you can add and subtract address rows when you run the heritage human service later in this example. You can now see a table with a column for each property defined in the Address business object. You can see an addresses 1 tab in the tab control. Select the table and in the General properties. By doing this step. select Show Add Button and Show Delete Button. Add a button control below the tab section and relabel it to OK. The button broadcasts a boundary event and you can use it to wire the coach in the heritage human service flow. Drag the addresses variable onto the tab control. 671 . B.9. C. Select the tab. D. In the diagram. .11. 13. Test the heritage human service by clicking the Parent topic:Coach and coach view examples Related information: Stock controls 672 button. connect the start node to the Customer coach and then connect the Customer coach to the end node. 12. Save your changes. This declares a dependency on the module that provides event handling for DOM nodes and related functionality. . As a result.In the Module ID column. Register the Dojo button module and alias that the coach view will load dynamically. C. In the Variables tab. Overview of tasks in this example: . 3. 2. create a new coach view named getAccountTypes.Example: creating a Select control using custom HTML This example shows how you can use scripts to bind selected values in a Custom HTML control to the business data of a coach view. type caseProperties (see Table 2). 2. see Adding custom AMD modules for information about how add and then access these 673 .Add custom HTML code to a coach view that defines a "Select" control for choosing an account type. from the palette under Advanced. select the Text option and then provide the custom HTML code. On the Layout tab. click the plus sign next to Business Data B. For the Variable Type. Before you begin. 1. type dojo/_base/connect. you can use the following code to define a "Select" control:<select name="AccountType" size="1"> <option value="Savings">Savings Account</option> <option value="Current">Current Account</option> </select> D. This is the alias used in the code to refer to the connect module. Tip: This example uses an AMD module that is included in the infrastructure. Configure the load event handler with a custom script for mapping the custom HTML selected value to the business data attribute. If the AMD modules are not already included. In the Name field.Add business objects to the coach view. In the Behavior tab. For this example. drag the Custom HTML item onto the canvas. you must be familiar with the coach view application programming interface (API) and you must have already created your Business Data business objects (see Table 2). select Can Fire a Boundary Event. you will create an Account Type selection list that can be reused or extended and then used across multiple coaches. such as Current or Savings. . In a toolkit or process application. type connect. Click Add and then specify the following information: . 1. Add business objects to the coach view. In the properties under HTML. Add custom HTML code to a coach view: A.Configure an event handler (load) with a custom script to bind the Select control selected value to the complex type business object attribute. A. On the Overview tab. C. select AMD dependencies. B. A. select the TSAPP_ValidateDocumentCaseProperties business object.In the Alias column. . context. On the Diagrams tab.connect(selectElement.connect(selectElement. function(newValue){ if(this.Tip:connec t. "onchange".context. Table 1.get("value"). this.connect(selectEl ement. Notes about the script Item (this == the view object) Description The load event has the context of payload data as well as that of the business data object associated with it (added in step 2). The new value selected in the Select control is bound to the business data specific attribute (TSAPP_AccountType).value). newValue. select the coach. To test your work using a human service.target.binding.connect. and private variable types. In the Behavior tab under Event Handlers. you can use the following script:var selectElement = this. the script would look like myConnect. if myConnect is the alias name.set("TSAPP_AccountType".element. The onChange event of the custom HTML control is called using connect. For this example.get( "value").modules.set("TSAPP_Accou ntType". tempBinding. On the Variables tab. this. create a heritage human service and then do the following: A. select load and then provide a custom script. On the Coaches tab.binding){ var tempBinding = this. 4. Therefore. For example. newValue. B. } }).binding. "onchange" is derived from the alias of the dojo/_base/connect entry in the AMD dependencies.context. "onchange" in the script has the new value selected in the Select control. output. drag the getAccountTypes coach view onto the canvas. add a coach. and then select the 674 . C.target.connect(selectEle The onChangeHandle variable ment. connect. var onChangeHandle = connect. "onchange".value). the script should be modified accordingly based on the alias name.getElementsByTagName("select")[0]. add TSAPP_ValidateDocumentCaseProperties as input. B.context. Reference Table 2. Example business objects Library item Business Objects Example name TSAPP_ValidateDocumentCase PropertiesParameters: TSAPP_Zipcode (String) TSAPP_Age (String) TSAPP_AccountStatus (String) TSAPP_CustomerType (String) TSAPP_Name (String) TSAPP_City (String) TSAPP_AccountType (String) In the coach view. TSAPP_ValidateDocumentCase Properties variable type is bound to caseProperites. A browser opens and displays the selection list. D. complete the wiring of the coach. Parent topic:Coach and coach view examples Related information: Coach and Coach View reference information Advanced items for coach views 675 .TSAPP_ValidateDocumentCaseProperties private variable as the binding. E. Click Run Service. On the Diagrams tab. In the Behavior tab.get("value").In the Alias column. Register the Dojo button module and alias that the coach view will load dynamically. Table 1. Under Event Handlers. B. type Button.get("value") the configuration options. var _this = this.Adding custom HTML code to a coach view .options. Notes about the script Item Description this. var button = new Button({ label: this.element.context. select the Text option and then provide your custom HTML code. B. In the HTML properties.context. you can use the following script:var buttonNode = this.label._metadata. This is the alias name used in the code to refer to the dijit button. Click Add and then specify the following information: . you can use the following code to define a button control:<input type="button" class="dojobutton" name="dbtnName" value="default"></input> 2. 1.context.context. drag the Custom HTML Advanced item onto the canvas. 676 .Example: creating a Dojo button control This example shows how you can use the Dojo library to implement a coach view. . 2._met Retrieves the label value from adata. For this example.options. select load and then provide the custom script. buttonNode). In the Layout page. This declares a dependency on dijit button module.In the Module ID column. Configure the load event handler with a custom script: A.trigger(function() { console.label.}) } }.querySelector("input"). select AMD dependencies. type dijit/form/Button.log("dojo button boundary event handled"). For this example. Add custom HTML code to a coach view: A. onClick: function() { _this. About this task This example provides steps for completing the following tasks: .Configuring the load method event handler with a custom code Procedure 1. 3.) Triggers a boundary event when the button is clicked. If the boundary event is wired to the next step in a heritage uman service diagram.this.trigger(.. clicking the button triggers a transition (to the next step). Save changes.context.. Results The custom button will be available in the palette. Parent topic:Coach and coach view examples Related information: Coach and Coach View reference information 677 . Uploading a managed file with the external library assets .get("value") the configuration options.Example: creating a jQuery button control This example shows how you can use an external third party library. you can use the following script:var _this = this.button( {label: this. $('.element). function() { _this. B.min. About this task This example provides steps for completing the following tasks: . when creating a coach view. Under Event Handlers. For this example.context.jquery-ui-1. click the plus sign next to Files and select Server File from the list of components.custom. Select your compressed jQuery library assets file (jQuery. In the HTML properties. select the Text option and then provide your custom HTML code.log("jQuery button boundary event handled").bind('click'. In the Layout page.css . Notes about the script Item Description this. The .context. the following files are included in the order that they are listed: .label.options.zip) file that contains the jQuery library assets and style sheets and then select the individual files to include: A.css 3.context. Select a file to include.context. For this example.8. drag the Custom HTML Advanced item onto the canvas. Each file to include is selected individually.zip to view the contents of the uploaded file.css files are included in a specific order.}) }). click the twistie next to jQuery.options.jquery-1. C.custom. In the list of server files.js .label. B._meta Retrieves the label value from data. For this example.Jquerybutton'.zip for this example) and then click Finish. Table 1.js .4. 678 .Configuring the load method event handler with a custom code Procedure 1._metadata.core. you can use the following code to define a jQuery button:<input type="button" class="Jquerybutton" name="jbtnName" value="default"></input> 2.Adding custom HTML code to a coach view . D.8.trigger(function() { console.get("value")}). such as jQuery. select load and then provide the custom script. Upload a compressed (.jquery-ui-1. From the list of library assets. Add custom HTML code to a coach view: A. After the upload is complete. this. E. go to the Behavior tab of the coach view and click the plus sign next to Included Scripts. .) Triggers a boundary event when the button is clicked..this. Results The custom button will be available in the palette. If the boundary event is wired to the next step in a Human service diagram.context. Save changes. clicking the button triggers a transition (to the next step). Parent topic:Coach and coach view examples Related information: Coach and Coach View reference information 679 .trigger(. 4. See Building a client-side human service. In the Coaches tab. For information about validating a coach in a heritage human service. The example contains a Prompt for Start and End Dates coach. an End date field. Procedure 1. from the Variables section of the palette. and set the type of each variable to Date.Example: validating a coach in a client-side human service This example shows you how to validate the data in a coach within a client-side human service using client-side validation. startDate and endDate. A coach validation pattern that consists of a script and an exclusive gateway that is used to validate the coach data. In the Variables tab for the human service. In the client-side human service diagram. see Example: validating a coach in a heritage human service. The example also demonstrates how to prevent the user from proceeding to the next step when the data is not valid. drop the startDate and endDate parameters onto the coach. The start date precedes the end date.Note: This example shows you how to validate a coach in a client-side human service using IBM® Process Designer. 3. 2. 4. and an OK button. Create the client-side human service that will contain the coach to be validated. rename the coach to Prompt for Start and End Dates. create two private variables. which has a Start date field. About this task The following example demonstrates how to validate the data that a user enters in the coach so that an error message shows up in the coach when the data is not valid. Leave the default OK 680 . 5. it has the / indicator to show that it is the default flow. and an intermediate event. In the diagram. Set the start date before the end date.getTime()) tw. Connect the script to the exclusive gateway. a validation error is recorded and the flow loops back to the coach.system. which automatically becomes a stay on page event.addValidationError("tw. The flow goes first to the script. C. The human service flow now contains a coach validation pattern. E.startDate". 6. The gateway determines the path that the flow takes.local.system. 7. Connect the coach to the script.getTime() > tw.endDate. Rename the flow line to Yes. Because this is the first flow line leaving the gateway. Repeat step 5 for the End date parameter to verify that it is correctly bound to the endDate variable. "The start date must precede the end date. In the coachValidation object.local. The second string is the message 681 . add a script.local. the first string contains the full variable path to the elements whose data is to be validated.coachValidation object. select the Start date parameter and ensure that it is bound to the startDate variable in the Behavior section of the General tab. 8. and then save the coach configuration. Connect the exclusive gateway to the end event. in the Script tab. the script creates and adds validation errors to the tw. an exclusive gateway. which is the end event.").coachValidation. Rename the script to Validate variable values and the exclusive gateway to Validation errors?. enter the following JavaScript construct:if (tw. Connect the exclusive gateway to the stay on page event. D. and try again. The stay-on-page event loops the flow back to the coach. Connect these elements in the following order: A. B. the flow goes to the next step in the flow. In the coach. If the data is not valid. If the data is not valid. If the data is valid.startDate. Delete the flow line between the coach and the end event. Select the validate variable values script and. if a coach view is bound to tw.coachValidation. which is a list. and then run the human service by clicking Run .If a coach view that is being validated contains rich text.If you are validating a list and you want the error to refer to the entire list.var3[]. which specifies what is wrong with the data and tells the user how to fix the problem.coachValidation. The human service completes successfully because both dates are valid. Click OK. Note: .length==0 . The browser highlights the Start date field and displays a warning icon.If the data element that is being validated is not bound to a coach view.local. 9. The test checks for the presence of validation errors and. the variableName parameter must include [] as a suffix. This matches coach view binding where [] indicates that the object is a list. create the test. Select the exclusive gateway and. Click OK. 11. "Var3 has validation error").addValidationError("tw. 10. Parent topic:Coach and coach view examples Related information: Validating client-side coaches using client-side validation Example: validating a coach in a heritage human service 682 . in its Implementation properties. there is nowhere to display a validation error if one occurs.system. routes it to the rest of the flow. If there are errors. Set the End date to a date that succeeds the start date.system. you need code like the following example: tw.for the user.local. test the validation by completing the following steps: A. B. the validation script must remove the formatting before validating the contents. you see a message that the start date must precede the end date. The test is tw. In the browser that displays the coach. If you hover over the warning icon.validationErrors. the flow goes to the stay on page event so that the coach can show the control with the problematic data and a message. For example. . .var3[]". Set the End date to a date that precedes the start date. if there are none. Save your changes. 5. 4. This sample uses the addCoachValidationError API to construct the business object. the service in the example uses a script to validate the data. the service must construct a CoachValidation business object to contain the validation information that it returns to the coach as output. drop the name. you can use any service type and you are not limited in how the service does the validation. 3. The Name and Salary fields must contain values. Relabel the default OK button to Submit. The example uses a general system service to validate the coach data. a Credit Limit field. For the sake of simplicity. a Salary field. The example shows how to validate a coach in a heritage human service using IBM Process Designer. In the diagram. The example contains a Credit Application coach that gathers information for a credit card application.creditLimit(Decimal) 2. 683 . Add application(CreditCardApplication) as a private variable.name(String) . For more information about validating a coach in a human service. and then open the coach. and creditLimit parameters onto the coach. Create the CreditCardApplication business object with the following parameters: . see Validating client-side coaches using client-side validation. To simplify the example. salary.Example: validating a coach in a heritage human service This example shows you how to validate the data in a coach within a heritage human service. 1. With the exception of Ajax services and human services. and a Submit button. From the Variables section of the palette. Create the CreateCreditApplication heritage human service. add the Create Application coach. and the Credit Limit maximum is double the Salary field value. the coach has only a Name field. However.salary(Decimal) . This change means that when the user clicks the Submit button. If the data is valid. Set Fire Validation to Before. connect the Credit Application coach to the start and end nodes. 8. Important: The name and the type of the service input must match the name and type of the coach variable that contains the data that you want to validate. create a general system service called CreditApplicationFormValidation. C. the flow then goes to the end node. The coach has an icon to indicate that you can now connect the coach to the validation service. the data validation does not occur and the flow goes directly to the end node. Select the connection between the Credit Application coach and the end node. The connection now has a check mark at its start. Create the service to validate the coach data: A. In this case. If you leave Fire Validation at its default of Never. Add validate(CoachValidation) as an output of the service. From the library. The presence of this output indicates that the service is a validation service. In the diagram. Add a server script to the service diagram and connect the start and end nodes to the script. 684 . add application(CreditCardApplication) as an input of the service.6. On the Variables page of the service. the flow first goes to the validation service to do the data validation. 7. B. The service must have one output only and it is of the CoachValidation type. the example uses the input to provide the data that the service validates. salary".addCoachValidationError(tw. The tw. The system passes error information back to the coach and users see an indicator beside the coach view with the problematic data.Important: . 12."). Add the CreditApplicationFormValidation service to the CreateCreditApplication heritage human service diagram. 11. if (tw. This construction loops the flow back to the coach if the data in the coach is not valid.application. more than one coach can use the same validation service or script. Select the CreditApplicationFormValidation service and open the data mapping properties.salary <= 0){ tw.salary + ". there is nowhere to display a validation error if one occurs.local.application.application.application.local.local.application.application.addCoachValidationError(tw. "tw.local.coachValidation parameter is the system variable that contains the validation information.validate.system.application.system.CoachValidation().application. .A coach can use only one validation service or server script to validate its data. users see the appropriate message 685 . "tw.salary){ tw. The second string is the message for the user.system.validate = new tw.local.validate parameter is the CoachValidation business object that contains the validation information.validate. Connect the validate node of the Credit Application coach to the CreditApplicationFormValidation service.If the data element being validated is not bound to a coach view.creditLimit > 2 * tw.addCoachValidationError(tw.object. If the validation service provides error messages. Add a Stay on Page node to the diagram. add the application private variable as an input map. } The tw.local. } if ( tw.local. In the implementation of the server script.coachValidation Important: The output mapping to the system variable is mandatory for the coach to use the service as a validation service. To provide the data to the validation service.creditLimit".local. The first string contains the full variable path to the data element with the problematic data.system. add the following variable as an output map: tw."). 13. 9.local.If a coach view being validated contains rich text. " + "The maximum credit limit is $" + 2 * tw.name". To map the output of the validation service to the CoachValidation object.validate. "The name cannot be empty.name == ""){ tw. "The salary must be above 0. add the following code to construct the CoachValidation business object:tw. . } if (tw.local.local.D. 10. "The credit limit cannot be more than double the salary. the validation service must remove any formatting before validating the contents.system. The message should identify what is wrong with the data or tell the user how to fix the problem.").local. Connect the CreditApplicationFormValidation service to the Stay On Page node.local. "tw. However. Leave the Name field empty. 15. but the flow always returns to a new coach. Click Submit. the system processes the boundary event to move to the next step.Run to continue. D. After you have debugged the validation path. test the validation by doing the following: A. B. Click Submit. and you have reviewed the debug info page. including tw. Parent topic:Coach and coach view examples Related information: Building coaches Building services Creating custom business objects in Process Designer Developing reusable coach views validate() Validating coaches in heritage human services Example: validating data in a coach that is used in a human service 686 . the validate boundary event path loops back and goes back to open a new coach. If the data is valid. Click Submit. C. select one of the following options: . The browser displays a message that the Name field cannot be empty. you do not see a visual error during debugging. Restriction:Pay attention to the following behavior when you debug a coach and step through each activity in the flow as the coach service is running: If coach data validation is required at a step. The human service now finishes because all three values are now valid. The browser displays a message that the salary must be more than 0. This option moves to the next step in the regular boundary event flow. Replace the 1 in the Credit Limit field with a 3. 14. type a 1 into the Salary field and into the Credit Limit field. Type a name into the Name field.system. Replace the 3 in the Credit Limit field with a 2. and replace the 1 in the Salary field with a 0.coachValidation error information. Because the validate boundary event response cannot go back to the originating coach during the debugging. Save your changes and then run the heritage human service by clicking the button. You can step through a coach and see the validation error on the debug page.when they hover over an indicator. In the browser that displays the coach. .Run to the next break point that is defined in the next step in a regular boundary event flow. The browser displays a message that the credit limit cannot be more than twice the salary. Click Submit. Replace the 0 in the Salary field with a 1. create the Ajax service. Save your work. Procedure 1. Drag another Coach to the right of List Supplier Parts. click New. If it sees a Q. Since Ajax services are a common form of service. Drag a Server Script from the palette to the canvas and name it Get Supplier Name.results[0]=("ProServ").local. and create another coach to display information. Click Diagram.local. and the Ajax service. A. Drag a Coach from the palette to the left side of the canvas. Beside Autocompletion Service. Select Get Supplier Name and click the Implementation tab in the Properties view. The second coach displays product information from the supplier selected. Note that the expected input and output variable names (text and results) and their types have already been created for you. Name the Coach Show Parts from Supplier. If it sees a P.local. Double-click Get Supplier Name. Name the service Display Supplier Parts. Name the coach Get Supplier Name. This code will select the QuickServ supplier name when Q is entered by a user and select the ProServ supplier name when P is entered. Create the heritage human service. understanding how to build coaches that call them and use their data can be useful to anyone building a heritage human service or a business process.results[0]=("QuickServ"). Select the text field and in the Properties view select the Configuration tab. Select Enable Autocompletion. 687 . the coach that calls an Ajax service. you are shown how to create a coach that calls an Ajax service.results = new Array().local.Example: creating a coach that calls an Ajax service You can quickly build coaches that call Ajax services and display data from those services. tw. if(tw.local. C. } else if(tw. Drag a Server Script to the right of Get Supplier Name . Change the Label field to Enter Supplier: Q for QuickServ or P for ProServ. Drag a Text field to the canvas. it returns the name QuickServ as the name of the supplier. B. About this task In this step-by-step example. The New Ajax Service window opens. Enter the name Get Supplier Name for the name of your Ajax service and click Finish.text=="P"){ tw.text=="Q"){ tw. Select the text field and in the Properties view select the General tab. The coach editor opens. The Ajax service examines a letter. Beside User Interface. click + and select Heritage Human Service. It is a complete and self-contained sample and does not have any prerequisites. Add the following JavaScript. it returns the name ProServ as the name of the supplier. Name the server script List Supplier Parts. Click Variables. product[0] = new tw.local. a Q for QuickServ or a P for ProServ. case "ProServ": tw.local. break.product[0].local.product[1].listOf.product[0] = new tw. Use private variables for data that should be hidden.50". tw. Name the input supplier and leave the type as String. tw. tw.supplier) { case "QuickServ": tw.50".ProductLine(). The binding in this case associates the input variable in the Human service with the text element. tw. tw.local.39".product[1].ProductLine().price = "$35. Click New to define a business object that will contain the product data.local.product[1].ProductLine().sku = "Z34RT1GF". description and price. Create a server script that lists the supplier data.product[1] = new tw. When the Business Object editor opens. tw.product[0]. Click Coaches. tw.local.sku = "Z34RT1GF".} Conect the Start node to Get Supplier Name and Get Supplier Name to End .ProductLine().sku = "YT76UJ8F". tw.object. } Click Variables and Add Private to create a variable for this data. Save your work. click Add in the Parameters section and add three variables: sku. A. click Select and choose supplier from the menu. switch (tw. In the Properties view.40". drag a Button beneath the text field.local.price = "$20.description = "Glass Pane". tw.local. Enter ProductLine for the business object name. Save your work.local.local.object.local.object.product[0].description = "Door Latch". tw. Beside Binding. Name the variable product. Click Is List as the variable will provide a list of items. Rename it Next.local.sku = "YT76UJ8F".local.local.product = new tw.price = "$37.product[0].description = "Window Sill".product[0]. Click Add Input to add a variable for the user's input which will determine the supplier.product[0]. Back in the Get Supplier Name coach.local.local.product[1]. tw.local. tw. select General. click the Implementation tab and add the following JavaScript:tw. tw. Select Get Supplier Name and select the Text field. Close the Ajax editor. Close the Business Object editor. 2. Double-click List Supplier Parts.product[1].price = "$67. 688 .local.ProductLine(). Save your work.object.product[1] = new tw. tw. Click Diagram. Save your work. Save your work. Save your work.description = "Door Bell Chimes". In the Properties view.object. that is.product[1]. Leave the type as a String. In the first user interface. Wire Get Supplier Name to List Supplier Parts. C. Save your work. Wire List Supplier Parts to Show Parts from Supplier. wire Start to Get Supplier Name. Click Show Parts from Supplier. A. In the next user interface you should see the parts displayed from either the QuickServ or ProServ supplier. Click the Run Service icon in the upper right corner of the Diagram view. In the coach editor. Create a coach to display the supplier data. 4. wire Show Parts from Supplier to End.3. Test your human service. Rename sku to Stock Keeping Unit. expand Variables and drag product from the palette to the canvas. B. Click Close. Parent topic:Coach and coach view examples 689 . Save your work. A table with names taken from the product variable is created. enter Q or P. Note that you do not need to explicitly bind the product variable to this coach as it was done for you when you selected product from the Variables section. The user interface should complete the supplier name with QuickServ or ProServ. B. A. Drag a Button beneath the table. Finally. Save your work. Rename it Close. Click Next. Using Sequence Flow to create arrows. Return to the Diagram view and wire your components together. the inspector can see the entire Inspection Report coach: . . Later. . this example does not contain any data. To concentrate on the user interface. the inspector can see the amount of space between the check boxes reduce so that they occupy less space: 690 .Example: creating a coach for tablets and smartphones This example shows how to create a coach that changes how it displays its contents according whether users see it in a desktop browser.For the tablet. The Inspection part of the coach is no longer visible. The coach contains two coach views: Findings CV and Inspection CV. the inspector can see the Findings part of the coach and the buttons.For the computer. To support this scenario. the coach in the example changes its layout to accommodate the different screen sizes of smartphones. The inspector then submits the final report. tablets. and computers. The inspector expands on the initial comments with additional information. In the scenario.For a smartphone. The inspector uses a tablet or smartphone to create the initial report. on a tablet. The inspector then saves the report as a draft. The Findings CV contains the information that the inspector fills out for the inspection while the Inspection CV contains information that does not change. the inspector returns to the office and opens the report on a desktop or notebook computer. This example creates a coach that is called Inspection Report. a heath and safety inspector arrives at a work site. or on a smartphone. F. In the Layout page. Lighting.Output Text . Click the for User Interface and then select Coach View. the layout arranges elements vertically so the controls are stacked one on top of the other. set the Label visibility to Hide. close it and open it in the web editor. Relabel the Text Area to Comments. For the name. from the library.Horizontal Section . This example adjusts the positioning of some of the controls and the layout in the web editor is closer to what users see at run time. add the following stock controls in order from top to bottom: . the layout of the coach view looks like the following screen capture: The layout in the desktop editor is similar. and Other.1. In the second horizontal section. select User Interface. Relabel the Check Box controls to Overhead. In the first horizontal section. In the general properties. If you are using the Process Designer web editor. The web editor also provides positioning properties to help you do the adjusting. Modify the appearance of the coach view: A. B. Trip. Relabel the Output Text control to Findings. A. G. Select the first horizontal section. To open it in the web editor. If the new coach view opens in the Process Designer desktop editor. 691 . Create the Findings CV coach view.Horizontal Section . 2. Furniture. H. C. Repeat this step for the other section. add a Select control and a Text control. Electrical. D. add six Check Box controls. enter Findings CV. Right-click the coach view and select Open in > Web Editor. Relabel the Select control to Building and rename the Text control to Area inspected. E.Text Area By default. In the HTML attributes. By setting this property. B. the labels for the check boxes are no longer in bold font. In its configuration options. Relabel the Text control to Inspector and relabel the Date Time Picker control to Inspection date. D. E. Repeat this step for the other check boxes. If you look at the coach view in the Layout page. E. add a Text control and a Date Time Picker control. add the following class: notBold. 3. Create the Inspection CV coach view A. In the Layout page. ensure that you set their type to String and Date. enter Inspection CV. in its general properties. In the Behavior page of the coach view. the section moves some of them below the others instead of displaying scroll bars. Click the for User Interface and then select Coach View. bind it to the 692 . add the following configuration options: . D. In the configuration properties.inspector(String) . } F. add the following code as inline CSS: . In the Variables page.notBold . C. Select the Inspector control and. enable Automatic Wrap. enable Show Border.controlLabel{ font-weight:normal. C. Repeat this step for the other section. Save the coach view.B. Select the horizontal section that contains the check boxes. To remove the bold from the check box labels. select a check box. For the name. if there is not enough room to display all of the controls side-by-side.inspectionDate(Date) When you create the configuration options. In the client-side human service diagram. In the second horizontal section. In the first horizontal section.F. In the Configuration properties of the section. In the first vertical section. Set the name to Inspection. G. Drag the OK button into the second section. E. add the Inspection CV coach view. add two horizontal sections. select the Inspection Report coach. enable Automatic Wrap. rename the coach to Inspection Report. 4. Rename the OK button to Cancel and rename the other two buttons to Save and Submit Report. H. Save the coach view. B. Select the Inspection CV coach view. C. controls. Create the Inspection client-side human service: A. 693 . add the Findings CV coach view. F. Define the layout of the Inspection Report coach: A. In the Coaches page. 5. In its configuration properties. In the second vertical section. add two vertical sections. B. Rename the two vertical sections in the first horizontal section to Findings and Inspection. C. add two Button stock D. In the layout of the coach. Click the for User Interface and then select Client-Side Human Service. type John Doe into the inspector property. Set a date in the inspectionDate property. Select the Inspection section. J. The elements in the Findings coach view must also align with each other. Alternatively. In its Visibility properties. type 20px in the Right field and 0px in the other fields. Run the Inspection human service. and the fourth number is for the left margin. you can click the icon beside the Margin field. Tip: Notice that the Building control and the Area inspected control are no 694 . Save the human service. open its configuration properties and select the Show Border property. In the positioning properties. the first number is for the top margin. Add more space between the Building and Area inspected controls. M. Click OK. In the Margin field. set Visibility to Read only. 6. the second number for the right margin. the third number is for the bottom margin. Repeat this step for the Inspection section. K. The web browser opens and displays the coach. Hide the title bars of the two horizontal sections by selecting them and. B. Open the Findings CV coach view and select the Building control. In the window that opens. set the margins to 0px 20px 0px 0px. A. L. For the Findings section. The information in this part of the report would come from the system so making it read only means that the user cannot change it. set their Label visibility to Hide.I. in their general properties. F. which sets all of its margins to 0 pixels. the section shifts to the right and this shift can lead to scroll bars for browsers that support them or it can lead to truncating 16 pixels. Save your changes. and Comments control to the right so that they align with the Building control: A. Without the width setting. C. set its Margin positioning property to 0px 20px 5px 0px. . Select the Comments control and set its Margin positioning property to 10px 0px 0px 16px. Change the margin of the Area inspected control to 0px. C. The Findings label and the border of the check box section now align with the Building control. For each check box control. In the coach. If the controls are nested within multiple sections as the Building and Area inspected controls are in this example. D. the section that contains the check boxes. Open the human service and then run it. Move the Findings output text control.Set the margins of the Area inspected control to 0px. 7. This is the approach chosen in this example. The five pixels added to the bottom margin helps even the space to the border above and below the check boxes. all of the controls in the coach view align at run time. This step completes the appearance of the coach when users view it using desktop monitors or notebook computers. Setting the width to 100% limits the width to the container or viewport width. Select the horizontal section control that contains the check box controls and set its Padding positioning property to 0px 0px 0px 16px. When you set a value for the margin. You can compensate for this situation in a number of ways: .5em as a margin around these controls.5em to the top margin of the Building control. 695 . E. you override this value and this change can cause some controls to move out of alignment. B.longer vertically aligned. Process Designer inserts . Set its Width positioning property to 100%. Select the Findings control and set its Margin positioning property to 0px 0px 0px 18px.Add . set its Visibility to None. Set its Margins positioning property to 0px 10px 5px 0px. C. D. Switch to the medium screen by clicking on the palette. If you reduce the width to 1024 pixels or less. This change halves the space between this check box and the Electrical check box. B. To reduce the amount of space between check boxes: A. the gaps between the check boxes narrow Parent topic:Coach and coach view examples Related information: Positioning options for coach view instances 696 . C. In its Visibility properties. If the browser is wider than 1024 pixels wide. Set the margins for the other check boxes to the same value. 9. E. Select the Inspection section. the Inspection section is visible. Open the Findings CV coach view and select the Overhead check box. To remove the Inspection section for viewing the coach on a tablet: A. Save your changes and run the human service again. B. If the browser is less than 640 pixels wide.8. Switch to the small screen by clicking on the palette. Save your changes and run the human service again. the Inspection section disappears. Create a heritage human service that is called My Human Service. you can still show their labels by using the label general configuration option. In the Overview page. there is nowhere to show their labels by default. you create the My Complex CV coach view with two text controls and a text area control. Open My Coach and add My Complex CV to it. B. Open the My Complex CV view. Connect the start node to My Coach and connect My Coach to the end node. 3. In this example. add a coach that is called My Coach. In the its diagram.Example: showing the label of a complex coach view This example shows how to show the label of a complex coach view in the coach or coach view that contains it. This is not the case for complex coach views. The following table shows My Complex CV within a coach at design time and at run time. The example uses a heritage human service and stock controls. You can use default values for the controls. However. You can substitute client-side human services. which contain multiple coach views. When you add complex coach views to a parent view or a coach. To make the view label visible at design time: A. In both cases. select Supports a Label. 2. Create a coach view that is called My Complex CV and add two text stock controls and a text area stock control to it. you cannot see the label for the view: My Complex CV in a coach in My Complex CV at run time the Process Designer 4. You then modify it so that you can see its label at run time. however this means that your results will look a bit different from the screen captures in the steps. 1. When you add simple coach views like controls to a coach or coach view. 697 . you automatically see their label at design time and at run time. 698 . In its layout. Open the My Complex CV view. add an output text stock control. Save the view. 5.C. If you open My Coach in the human service. you can now see the label for My Complex CV. B. To make the label visible at run time: A. the name is styled as a label. Save the view. B. the name is styled as normal text. 6.C. In the window that opens. at runtime. Save the view. In the General properties of the output text control. Open My Human Service and open My Coach. 699 . at runtime. Change the label of My Complex CV to My Complex CV Label. If you instead set the binding to display the coach view. Test that you have bound the coach view label: A. Using the label of the output text to display the coach view name means that. click for the Label field and then clickSelect. expand General Options and then select label (String). D. C. The following table shows My Complex CV at design time and at run time. My Complex CV in a coach in My Complex CV at run time the Process Designer Parent topic:Coach and coach view examples 700 . Run the human service. My Complex CV now shows the label that you give it in My Coach. . After you have designed the look and feel of the Heritage Coach. . . Parent topic:Creating user interfaces for business processes Related information: How heritage coaches work 701 .Adding sections to a Heritage Coach and controlling the layout Use the Heritage Coach Designer to build an initial mockup of a Heritage Coach. override CSS styles. .System services to implement conditional activities The System Data toolkit includes services and a Heritage Coach that can serve as a template to implement and manage conditional activities.Building Heritage Coaches When you build heritage human services you can use Heritage Coaches. . . bind variables to Heritage Coach controls.Troubleshooting Heritage Coaches Learn how to identify and fix common problems with Heritage Coaches. This requires creating bindings between the Heritage Coach controls and the data structures (variables) that represent the business data within your IBM® Business Process Manager processes. or perform other customization tasks when creating Heritage Coaches.Adding documents and reports to Heritage Coaches You can upload documents and embed reports for display in Heritage Coaches. . which provide the interfaces for end-user interaction.Examples of building services with heritage coaches There are examples of building services and then combining them with heritage coaches. your goal may be to build a mockup with static elements so that you can visualize what data is needed in the runtime Heritage Coach. you need to feed real business data to the Heritage Coach controls for your process participants to interact with and to help them make the appropriate decisions. and perform other tasks to configure the controls in your Heritage Coaches.Configuring Heritage Coach controls Learn how to make Heritage Coach controls required fields.Customizing Heritage Coaches You can include custom images. In the first stage of designing a Heritage Coach. and where the data should be displayed in the layout. and from the pop-up menu that opens. select Delete. Click an Input Text control in the design area and in the properties. 4. You can add sections and controls and adjust the layout for your Heritage Coach. Procedure 1. The mockup allows you to demonstrate the design to users as you develop a plan for the steps within a process. Drag a One-Column with Title section from the palette onto the design area so that it is positioned directly below the existing Customer Information section. 3. change the title of the Heritage Coach by clicking the IBM® Business Process Manager Heritage Coach title bar in the design area. type Case Information in the Title text box in the properties. While the new section is still selected.Phone: . Right-click the default Checkbox control. the Heritage Coach includes several controls. 10. 5. a Checkbox control. About this task When you create a Human service and drag a new Heritage Coach from the service palette to the diagram. The following steps describe how to build a mockup of a Heritage Coach that enables personnel in a call center to collect data about customer issues. Click the Section Title in the design area and in the properties type Customer Information in the Title text box. Neither of these controls is needed for this sample Coach. Change the text labels for the fields. A new Heritage Coach contains a single-column section with a title that includes an Input Text control. In the Heritage Coach option of the properties. 6. Drag a Text control from the palette onto the design area and place it in the new Case Information section.Physical address: 7. You can use feedback from users to refine the design and thus help guarantee that the eventual implementation meets all requirements. 9. Drag four Text controls from the palette onto the design area so that two Text controls are in each column side by side.Email: . 8. Drag a Two-Column section from the palette onto the design area so that it is positioned directly below the existing Section Title. change the Label for each control to match the following list: . type Initiate New Case Enter Customer Information. To start developing the mockup. by default. Do the same for the default Input Text control. and a button Group. 702 . 2.Name: .Adding sections to a Heritage Coach and controlling the layout Use the Heritage Coach Designer to build an initial mockup of a Heritage Coach. Select the Presentation option in the properties and in the Manual Data section. You can make adjustments as you see fit in the Design tab.11. 16. These values will appear in the user interface at run time. 15.Setting the number of columns in a Heritage Coach Learn how to set the number of columns for each section of a Heritage Coach. In this version a service gets input data at run time which is used to populate the values of the drop-down list. 17.Table 1. In the Manual Data section.Important: The action associated with any given button applies only to the fields and other controls in the same section as the button.Lets change this scenario slightly. use the Add button to add the values and display text shown in Table 1. 12. Click the default Button Group at the bottom of the design area. Drag a Date Selector component from the palette onto the design area and place it directly below the drop-down control in the new Case Information section. Then choose Single Select from the Control Type field under the Behavior section. Save your work. While the new Text control is still selected. type Case Type in the Label text box under the Common section. click the Presentation option in the properties. Add values and display text. click the Add button. Since these values are only known at run time. Click the Preview tab to see how the Heritage Coach will look when the service runs. .Setting column widths in a Heritage Coach Learn how to change the column width for each section of a Heritage Coach. In the properties for the Date Selector component. Values and display text to add under the Manual Data section Value billing defect tracking Display text Billing Product defect Late Shipment 14. . 13. the values will not appear when you press the Preview tab at development time. change the label to Date Received . 18. and change the label for the OK button to Submit. Parent topic:Building Heritage Coaches Related information: Configuring heritage coach controls 703 . 3. 5. 4. Parent topic:Adding sections to a Heritage Coach and controlling the layout Related information: Setting the number of columns in a heritage coach 704 .Setting column widths in a Heritage Coach Learn how to change the column width for each section of a Heritage Coach. In the design area. Click one of the columns listed to enable the Column Width text box. Specify the width of the column in the Column Width field using any valid HTML size attribute such as 50% or 110px. If you selected a section containing more than one column. Procedure 1. Click the Preview tab to see how the Heritage Coach layout will look when the service runs. Click the Presentation option in the properties. click the section that contain the columns you want to set. 2. Open the service that contains the Heritage Coach that you want to change and then click the Coaches tab. each column is listed in the Columns area in numeric order based on the column ID. Procedure 1. In the design area. 4. Open the service that contains the Heritage Coach that you want to change and then click the Coaches tab. Click the Section option in the properties and then click the up and down arrows for the # of Columns option to increase or decrease the number of columns in the section. click the section that you want to change. Click the Preview tab to see how the Heritage Coach layout will look when the service runs.Setting the number of columns in a Heritage Coach Learn how to set the number of columns for each section of a Heritage Coach. In the following example. Notice the behavior of the nested section when its parent section is configured. one additional column is added to a section that contains a nested two-column section. 3. Parent topic:Adding sections to a Heritage Coach and controlling the layout 705 . 2. Building a heritage human service with heritage coaches Build a heritage human service when you want a step in your business process definition (BPD) to create an interactive task that process participants can perform in a web-based user interface. The examples contained in this section work with heritage coaches. Parent topic:Building Heritage Coaches 706 .Examples of building services with heritage coaches There are examples of building services and then combining them with heritage coaches. and how to build a Heritage Coach to work with that service. such as a database.Example: Building a heritage human service with coaches Build a heritage human service when you want a step in your BPD to create an interactive task that process participants can perform in a web-based user interface. About this task The steps that you perform to build a service is the same whether that service works with a coach or heritage coach. You can use an Ajax service to pull data dynamically from a connected data source. . .Example: building an integration service with a Heritage Coach This example consists of two topics that show how to nest an integration service.Building an Ajax service with Heritage Coaches The Ajax services that you build in IBM® Business Process Manager can be subsequently bound to coach controls to perform functions such as automatically populating drop-down lists and enabling type-ahead capability in input fields. . . Building Heritage Coaches to collect input and display output This example shows how you create a Heritage Coach in the parent service to control variables. you can nest an integration service that calls a web service to display the list of options.Example: building an integration service with a Heritage Coach This example consists of two topics that show how to nest an integration service.Map the input and output variables for the nested integration service. .Create a human service that implements the integration service as a nested service. . In that case. About this task For example. . Read the following topics to learn how to: .Create the Heritage Coach interfaces to collect the input and display the output for the nested integration service. Parent topic:Examples of building services with heritage coaches 707 . and how to build a Heritage Coach to work with that service. Integration services are the only services that can include Web Service Integration and Java Integration components.Nesting the Integration service and mapping its variables This example shows how you nest an integration service inside a human service to work with a Heritage Coach. . you want users to choose from a list of products available from a common site on the internet. Procedure 1. making it available to all components in the parent service. 2. indicating that a matching private variable was not found in the parent service. Create a heritage human service as described in Building a heritage human service and name it according to what the service performs. Click Save in the main toolbar. Parent topic:Example: building an integration service with a Heritage Coach 708 . click the auto-map icon. click the nested service in the diagram to view its properties. A private variable of that name is created for the parent Service and automatically mapped to the input variable of the nested service. From the Input Mapping section. 7. Because you already created the input and output variables for the nested service. the Data Mapping tab for the parent service includes those variables. perform the automapping step to create the matching private variable to capture the output from the nested service. 8. This creates the Nested Service component with the service attached in a single step. From the Output Mapping section. 3. The Create variables for auto-mapping dialog box opens. 4. and should be created.Nesting the Integration service and mapping its variables This example shows how you nest an integration service inside a human service to work with a Heritage Coach. Select the suggested variable item and then click OK. 6. If not already selected. 5. you can drag the existing service directly from the library to the diagram of the parent service. Open the diagram for the new human service and drag the integration service from the library to the diagram. You can see the private variables added for the parent service. When you have an existing service that you want to nest in another service. 14. Click the Diagram tab to return to the diagram view of your service. To test your service. click the Select button to create a binding to the results variable. Drag another Heritage Coach from the palette to the diagram and name it View search results . click the Step option in the properties and type a name for your coach in the Name field. 3. drag an Output Text control to the Heritage Coach. Drag the variable that you declared for your integration service from the palette to the Heritage Coach. In the Heritage Coach. find and select the appropriate output variable. 7. Place the Heritage Coach component before the nested service component. 4. 16. click the Presentation option. In the properties. select the Output Text option in the properties and in the Behavior section. The Heritage Coach opens in your browser. 11. and a label that matches the variable. While the Heritage Coach component is selected in the diagram. Click the Coaches tab. About this task Complete the following procedure to create the Heritage Coach interfaces in the parent service. Procedure 1. click the Run icon in the upper right corner. From the list that opens. 17. From the palette. and map the associated controls to the variables from the previous procedure. Click Save in the main toolbar. Select the Sequence Flow tool from the palette and then connect the components. Click the Preview tab for the Heritage Coach to see your label change. 6. click OK definition and type Search in the Label text box. An input text field is created with a mapping to the variable. 10. 9. Click the Diagram tab for your service. Click Save in the main toolbar. and then in the properties. 5. 8. In the Buttons section.Building Heritage Coaches to collect input and display output This example shows how you create a Heritage Coach in the parent service to control variables. 15. select the group containing the default OK button. Place the Heritage Coach component after the nested service component. Click the Coaches tab. 13. 2. 12. Click the Diagram tab for your service and then drag a Heritage Coach component from the palette to the diagram. Parent topic:Example: building an integration service with a Heritage Coach 709 . make the following selections:Table 1. 2.Building a heritage human service with heritage coaches Build a heritage human service when you want a step in your business process definition (BPD) to create an interactive task that process participants can perform in a web-based user interface. In Activity Wizard . The request variable is an EmployeeReimbursement business object. the activity is initially implemented using the default human service. drop-down menus. Procedure 1.Setup Activity. For your own implementation. right-click the Enter Expenses activity and select Activity Wizard from the list of options. About this task When you build human services and heritage human services. The service in the sample enables employees to enter expenses for the Expense Reimbursement BPD. you might not use the same steps or names. you must be in the IBM® Process Designer desktop editor. Coaches enable you to easily add standard fields and controls such as radio buttons. See Creating custom business objects in Process Designer for information. which are the web-based forms that provide process-related data to users as well as collect input from those users. You can double-click an activity in a non-system lane to open the default human service. Heritage coach support is not provided for human services. type(String). Recommended selections in Activity Wizard . amount(Decimal). Note: The following procedure shows how to use the Activity Wizard to create a heritage human service. This BPD contains an activity called Enter Expenses and a private variable called request.Note: You can include heritage coaches only in heritage human services. Starting with the Expense Reimbursement BPD. you can get an idea of how human services work and how coaches are used to display and collect data from process participants.Setup Activity Option Activity Type Selection User Task 710 . and status(String) parameters. You can also create a heritage human service from scratch as described in Building a heritage human service. you include coaches. which has id(String). Before you begin To perform this task. By examining the service components and running the default service in the Inspector. If you add an activity to a non-system lane in a BPD. and so on. The following steps describe how to build a sample heritage human service using example values. In the properties. Click the Preview tab at the bottom of the coach designer to view the coach. click the Next button. 711 . go to the Buttons section and click Add. The new service is created and attached to the activity. The new service includes a single Coach. select the control that contains OK in the coach designer. For this sample. click Add to add a value and associated display text for each option that you want in the drop-down list. Under Widget Style. In the coach designer. 8. You can see the private variable named request. choose the existing process variables to use as input and output for this new service. click the drop-down list for Control Type and choose Single Select.Setup Activity.Parameters. See Building heritage coaches for more information about the coach designer. In Activity Wizard . 5. 6.) 4. A. the Id: field label matches the parameter in the request variable. 11. In the properties. To add a Cancel button to the coach. Click Save in the main toolbar. B. To enable employees to select from an existing list of employee types. select Drop Down List for Widget Type.)The items in the palette are described in the links at the bottom of this page. B. in the properties for Employee type. 13. the palette shows all the elements (sections and controls) that you can use in a coach. Because you used the Activity Wizard. This enables you to collect the data for the expense using this new service and then output those values for the subsequent process steps to act upon. right-click the Status control and select Delete from the list of options. The new service opens in the Designer. The Preview tab shows how the coach will appear to users when the BPD runs. 7. Click the Coaches tab and then click the listed coach component. enter Cancel for the label and click Is Cancel.Service Selection Enable the radio button for the Create a New Service or Process option 3. Change the label to Employee type:. B. Double-click the activity for which you created the new heritage human service using the Activity Wizard. In the Presentation properties. In the Button Details. 9. Select Presentation in the properties. set Input to false and leave Output set to true. 10. (The name for this sample service is Enter Expense. Click the Finish button. the coach includes a form element for each of the parameters in the request structure. Click the Type control. Notice that when the coach designer is open. 12. but is a value set later after a request is further processed and so it can be removed. 14. A. Under Manual Data. The status of a request is not data that we need to collect from employees. Type a name for the new service in the Name field. The coach designer is where you customize the coach layout and create or edit the bindings between inputs and outputs. Click the Id control. (Hover over a control to view a brief description. A. In Activity Wizard . the Type: field label matches the parameter in the request variable. Change the label to Employee ID: so that employees know exactly which ID to provide. Click Run Service in the upper right corner to view the coach in a web browser.15. Parent topic:Examples of building services with heritage coaches 712 . B. Click Finish. the activity is initially implemented using the default heritage human service. 5. For your own implementation. see Creating custom business objects in Process Designer. 713 .Setup Activity. set Input to false and leave Output set to true. The new heritage human service is created and attached to the activity. which has id(String). Type a name for the new heritage human service in the Name field. The new service includes a single coach. 3. you can get an idea of how heritage human services work and how coaches are used to display and collect data from process participants.Parameters. Procedure 1. In Activity Wizard .) 4. Note: The following procedure shows how to use the Activity wizard to create a heritage human service. For more information. For this sample. This BPD contains an activity that is called Enter Expenses and a private variable called request. The following steps describe how to build a sample heritage human service using example values.Example: Building a heritage human service with coaches Build a heritage human service when you want a step in your BPD to create an interactive task that process participants can perform in a web-based user interface. In Activity Wizard . make the following selections: . Starting with the Expense Reimbursement BPD. You can see the private variable named request. About this task If you add an activity to a non-system lane in a BPD. select User Task. and status(String) parameters.Setup Activity. In Activity Wizard . You can double-click an activity in a non-system lane to open the default heritage human service. right-click the Enter Expenses activity and select Activity Wizard from the list of options. The request variable is an EmployeeReimbursement business object. click the Next button. By examining the service components and running the default service in the Inspector. A.Under Library Element Selection. (The name for this sample service is Enter Expense. choose the existing process variables to use as input and output for this new service. This enables you to collect the data for the expense using this new service and then output those values for the subsequent process steps to act upon. Before you begin To perform this task. you might not use the same steps or names. . amount(Decimal). You can also create a heritage human service from scratch as described in Building a heritage human service. The service in the sample enables employees to enter expenses for the Expense Reimbursement BPD. select Create a new heritage human service. type(String). 2. start the Process Designer desktop editor.Under Activity Type Selection. The status of a request is not data that is collected from employees. 9. 7. Change the label to Employee type. the Palette view shows all the elements (sections and controls) that you can use in a coach. A. enter Cancel for the label and click Is Cancel. Parent topic:Examples of building services with heritage coaches 714 . 11. you can see the label for the field is Id: to match the parameter in the request variable. The new heritage human service opens in the heritage human service editor in the Designer view. B. 10. The coach designer is where you customize the coach layout and create or edit the bindings between inputs and outputs. In the properties. Under Widget Style. To add a Cancel button to the coach. Select the Presentation option in the properties. the coach includes a form element for each of the parameters in the request structure. but is a value set later after a request is further processed and so it can be removed. For more information about the coach designer. Click Save in the main toolbar. Click Id (input text field). In the Button Details field. Click the Coaches tab and then click the listed coach component. You can also click Run Service in the upper right to view the coach in a web browser. Because you used the Activity wizard. In the properties. see Building heritage coaches. right-click the Status control (input text field) and select Delete from the list of options. 14. The Preview tab shows how the coach appears to users when the BPD runs. A. select the control that contains OK in the coach designer.The items in the palette are described in the links at the bottom of this page. Double-click the activity for which you created the new heritage human service. go to the Buttons section and click Add. In the Presentation properties for the control. To enable employees to select from an existing list of employee types. from the Control Type list choose Single Select. Hover over a control to view a brief description. B. 13. in the properties for Employee type. 12. Change the label to Employee ID so that employees know exactly which ID to provide. Click the Preview tab at the bottom of the coach designer to view the coach. Notice that when the coach designer is open. Click the Type control (input text field). 8. you can see the label for the field is Type to match the parameter in the request variable. click Add to add a value and associated display text for each option that you want in the drop-down list. select Drop Down List for Widget Type. In the coach designer. Under Manual Data.6. Select Ajax Service. be sure to enable the Is List check box for the ProductInfo output variable.listOf.local. Click the Diagram tab and then click the Server Script component in the diagram. For example if you were planning to use the service to accept the name of a supplier. you might have the following script using the specified variables sku .ProductInfo[0].local.tw.ProductLine(). tw. In the example described above.local. For example. switch(tw.ProductInfo=new tw. and price. enter the script for the Ajax service to run. With the new service open in the diagram editor. tw. tw.ProductLine(). drag a Server Script component from the palette.ProductInfo[0] = new tw. because you are expecting multiple products to be returned. 715 .ProductLine(). and click the plus (+) sign.ProductInfo[1] = new tw. and use sequence lines to connect the script to the Start and End Events.ProductInfo[0].sku = "Z34RT1GF". You can use an Ajax service to pull data dynamically from a connected data source.price = 3540. For more information on how to create variables see Declaring and passing variables and Creating custom business objects in Process Designer. In the left hand navigation.local. ensure that the Has Default check box is enabled. 6.description = "PowerServ 1500".local.object. description . you can create a new business object called "ProductLine" which contains fields for product SKU.local. and return a set of product information.ProductInfo[0]. 5. In the Implementation properties. if you were building a form for users to look up product information based on a supplier name. 4. you might create an input variable called "Supplier" of type string and an output variable called "ProductInfo".object. Also For the Supplier variable. you might have a service called "Query Product Line".Tip: For this example. and price for two different suppliers: QuickServ and ProServ. such as a database.object.Building an Ajax service with Heritage Coaches The Ajax services that you build in IBM® Business Process Manager can be subsequently bound to coach controls to perform functions such as automatically populating drop-down lists and enabling type-ahead capability in input fields. Procedure The first part of this procedure takes you through the steps of creating an Ajax service.Supplier) { case "QuickServ": tw. 2. hover over the Implementation category. Name your new service. Subsequent steps describe how to associate this service with a coach in order to populate fields in a user interface or form. Declare the variables to pass into and out of your service in the Variables tab. description. tw. 1.local. 3. Because the product information is complex. Click the Variables tab and add a private variable named product of type ProductLine . 10. 3. reload the browser page. tw.description = "Reliant X1". tw.ProductInfo[0].ProductInfo[1].local.local. Drag a Coach from the palette to the service diagram and then use sequence lines to connect the Coach to the Start and End Events. Drag the product variable from the palette to the Coach editor. Click the Input Text control in the Coach editor to select it and then click the Input Text option in the properties.local. tw. case "ProServ": tw.local.description = "PowerServ 1735". select Ajax Service . This automatically creates a table control. Click the Presentation option in the properties for the table control and in the Dynamic Data section. Now you need to associate the Ajax service you just created with a Human Service containing a coach.ProductInfo[1]. 5. } 7.local. 7.price = 6750. Create a new Human service or open an existing one. Change the Label field for this control to Supplier:. Click the Run Service button in the upper right corner. Click the table control in the Coach editor to select it. break.local. 4. you could create a Human Service named Select Supplier . tw.object. 8. tw.description = "Reliant DW". Parent topic:Examples of building services with heritage coaches 716 .price = 2039.local.ProductLine().ProductInfo[1] = new tw.local.ProductInfo[1]. 1.local. tw.ProductLine().sku = "YT76UJ8F". Click the Coaches tab and then drag a Text control from the palette to the Coach editor. Save your work. 9. Save your work. tw. From the Choose Control as Input drop-down list. Add variables to your new Human Service.ProductInfo[1]. 6. 12. Enable the Is List and Has Default check boxes for the product variable.price = 3750. To continue with the example above.object. If the supplier information does not immediately display.ProductInfo[0] = new tw.ProductInfo[1].sku = "Z34RT1GF".ProductInfo[1].tw.sku = "YT76UJ8F".local.local. tw. Click the Select button and choose the Query Product Lines Ajax service. 11.ProductInfo[0]. the Coach displays the information for that supplier. select Supplier (Input Text) . tw. 2. The Coach runs in a browser and when you provide one of the Supplier names included in the Ajax script (QuickServ or ProServ).ProductInfo[0]. Binding a complex data structure to a Table control in a Heritage Coach Learn how to bind a complex data structure to a Table control in a Heritage Coach.Populating a list with static data in a Heritage Coach Learn how to demonstrate the type of data that a Heritage Coach will display at run time. . you have several options for configuring the Heritage Coach controls that you add. . Parent topic:Building Heritage Coaches 717 .Displaying a control based on the input value of another control in a Heritage Coach You can create a control that is displayed only when a related control is set to a specific value. .Populating a list with dynamic data in a Heritage Coach Learn how to populate a list of options with dynamic data.Changing the visibility of a Heritage coach control Use a custom script to override the default visibility rules for a particular control in a Heritage coach. .Binding a variable to a custom HTML component in a Heritage Coach Learn how to render the content in an HTML block using the runtime value of a variable. Read the following topics to learn more: .Making an input control a required field in a Heritage Coach You can make input mandatory by configuring a Heritage Coach control as described in this procedure.Validating user input Add validation scripts for button controls in Heritage coaches to ensure that users provide all required input.Populating a table control using an SQL query in a Heritage Coach Use the Execute SQL option to retrieve data directly from a data source.Displaying a control to a specific group in a Heritage Coach Learn how to display a control to only those users who are members of a particular group. and perform other tasks to configure the controls in your Heritage Coaches. .Configuring Heritage Coach controls Learn how to make Heritage Coach controls required fields. . When building Heritage Coaches.Controlling field and other formatting in Heritage Coaches Learn how to add field formatting capability to Input Text and Output Text controls and align button controls. . . . bind variables to Heritage Coach controls. . 2. 4. enabling IBM® Business Process Manager users to view and interact with the data. Click the Preview tab to see how the list will work when the service runs. Open the service that contains the Heritage Coach that you want to work with and then click the Coaches tab.Populating a list with static data in a Heritage Coach Learn how to demonstrate the type of data that a Heritage Coach will display at run time. Under Manual Data. 5. click the Add button to create a row for each option that you want to add to the list. Drag a combo box control from the palette onto the design area. a Heritage Coach displays business data that resides in a variable. The value that you type in the Display Text column is the name of the option that is displayed to the user at run time. About this task Typically. Parent topic:Configuring Heritage Coach controls Related information: Populating a list with dynamic data in a heritage coach 718 . Procedure 1. Click the Presentation option in the properties. The following example illustrates a combo box control that uses static data to populate a list of options. you may need to populate a Heritage Coach with static (manual) data so that you can illustrate the type of data that the process will display at run time. 3. In the initial design stages. . Because these values are only known at run time. click Add to include static instructions at the top of the dropdown list. click Select to choose the preexisting variable from the library. These values do appear in the user interface at run time. the values do not appear when you select the Preview tab at development time.. Declaring and passing variables The following procedure and Building a heritage human service for an example Building an Integration service for an example About this task The following procedure illustrates a combo box control (single-selection list) that uses a preexisting process variable to populate a list of options. for the Based On option. Note: You can also bind Ajax services to Heritage Coach controls to perform actions such as automatically populating drop-down lists and enabling type-ahead capability in input fields. 4. Drag a Combo Box control from the palette onto the design area. click List Variable. See the following topics to learn more. Open or create a service for which you have declared a variable that is a complex structure. click the Presentation option in the properties.Populating a list with dynamic data in a Heritage Coach Learn how to populate a list of options with dynamic data. Click the Preview tab to see how the list works when the service runs. the control must be bound to a complex structure that is a list. Procedure 1. While the Combo Box control is still selected. Under Dynamic Data. 7. you need to create the appropriate variables for your process or service.. Table 1. 2. For more information. For this example. see Building an Ajax service . 6. A service inputs data at run time which is used to populate the values of the drop-down list. 3. Open the service that contains the Heritage Coach that you want to work with and then click the Coaches tab. Under Manual Data. For this example. the static text is: -. 719 .. Create variables for a process How to map those process variables to Heritage Coach controls Map variables to a nested service and then bind those variables to Heritage Coach controls See. Before you begin Before you can bind dynamic data to a coach control. Additional information for variable setup To learn how to. For the Dynamic Binding option.Select Dept 5. Parent topic:Configuring Heritage Coach controls 720 . Right-click and select Delete for the parameters that should not be displayed as output text. You can create the table and the bindings automatically by dragging the data structure to the Heritage Coach. The Heritage Coach displays the information submitted in the requisition to enable the General Manager to make a decision. You can see this process and its variables in the Hiring Sample process application. you do not have to create the table and then bind each element of the table to the appropriate variable parameter. A complex data structure is a private variable in an HR process used to submit requests to open new positions. See Building a heritage human service for an example. select all remaining fields and change the Control Type to Output Text.Binding a complex data structure to a Table control in a Heritage Coach Learn how to bind a complex data structure to a Table control in a Heritage Coach. At one point in the process. Click the Preview tab to see how the table will look when the service runs. a General Manager must approve a submitted request. Drag the input requisition variable from the palette to the design area. you must first create the data structure and declare it in the service where you want to build a Heritage Coach. Procedure 1. 2. Parent topic:Configuring Heritage Coach controls Related information: Populating a table control using an SQL query in a heritage coach 721 . 4. The GM Approval service (in the Hiring Sample process application) includes the requisition variable as both input and output. Before you begin Before you can perform this task. the Heritage Coach displays the table with the appropriate data for the manager to act upon. To display the values of the parameters in the requisition variable in a Heritage Coach. Note: You can also use the Activity Wizard to automatically create Heritage Coach control bindings. (For more information see the IBM Business Process Management Information Center. This enables the Heritage Coach to display the requisition parameters to the General Manager and then the service passes the values of the parameters in the requisition variable back to the BPD for processing by subsequent steps in the process. When you run the tutorial BPD. 5. Click the Section option in the properties and increase the number of columns to 2. click the Coaches tab. 3. About this task If you have created a complex data structure and you want to bind it to a Table control in a Heritage Coach. 722 . About this task The Execute SQL option enables you to populate a table control dynamically. In the Data Source text box. The value of the ITEM_NAME column is displayed in the Item Name column. The following procedure illustrates how to use the Execute SQL option to dynamically populate a Table. For example. If you use a non-XA data source. Before you begin Before using a SQL query to populate a Table control.The Execute SQL option is only used for retrieval of data (insert. click the Presentation option in the properties. without having to initialize the variable first. you might receive an error about a database connection failure. displaying it in the column to which it is bound in the Heritage Coach. and employee type from a table named R2H_PositionType by entering the following text:select id. . If the property names do not match the column names. Click the Execute SQL check box to enable it. Procedure 1. and only if the variable to which the table is bound has no current value. you could select the ID. if the Service updates the value during the life of the runtime task. enter an SQL query to select the data that you want from the data source. you can use column aliases in your SQL statement to perform the correct matching. Open the service that contains the Heritage Coach that you want to work with and then click the Coaches tab. The following example:SELECT PRICE AS Cost. the data source is "jdbc/TeamworksDB" . Note that the names are not case-sensitive. In the SQL text box. . By default. be aware of the following: . 3. employeeType from R2H_PositionType 723 . or an emulated XA data source. 5. select the Reload option. For example. ITEM_NAME AS ItemName returns the value of the PRICE column to the Cost property in your custom data structure. status. When executing the SQL query. 6. When you want to use a data source other than the jdbc/TeamworksDB data source. Drag a Table control from the palette onto the design area. status. While the Table control is selected. If you want to refresh the value every time the Heritage Coach is rendered. update. you would want to reload this value each time the Heritage Coach is rendered. and delete operations on data are not allowed).The SQL query is run before the Heritage Coach is displayed. IBM® Business Process Manager uses these labels to match the values from the columns to the correct rows in your Heritage Coach table. ensure that it is an XA data source. type the data source from where you want to retrieve the data.Populating a table control using an SQL query in a Heritage Coach Use the Execute SQL option to retrieve data directly from a data source.The property names of your custom data structure must match the column names in the database table that you want to query. 4. 2. which points to IBM BPM databases. Parent topic:Configuring Heritage Coach controls 724 . Use an ORDER BY clause in your SQL statement to override this behavior.The order of the entries is in the order which the table rows are returned. run the service.myHTMLBlock is declared in the Variables tab for the service and then used to set the label of the HTML block at run time. While the Custom HTML control is selected. For a quick test. Procedure 1. type the variable whose value will populate the HTML block at run time. 5. Open the service that contains the Heritage Coach that you want to work with and then click the Coaches tab. Select the variable and then. The Heritage Coach displays the runtime content of the HTML. In the HTML text box. 2. To render the content in the HTML block. Parent topic:Configuring Heritage Coach controls Related information: Binding a complex data structure to a Table control in a heritage coach 725 . click Has Default. 3. The following example shows how to render the content in an HTML block using the runtime value of a variable. click the Presentation option in the properties.Binding a variable to a custom HTML component in a Heritage Coach Learn how to render the content in an HTML block using the runtime value of a variable. tw. In this example. the variable is evaluated and its runtime value is then passed to the Heritage Coach. under the Default Value section.local.myHTMLBlock#><p> . Drag a Custom HTML control from the palette onto the design area. 4. define a default value for the variable from the Variables tab. When you run the service. Type the following in the HTML text box: <p><#=tw. When Has Default is selected and the default value is added to the field. About this task The Custom HTML component can be used in a Heritage Coach to accomplish a variety of runtime data presentations.local. which is This is the default value that can be used to test the Coach. and under what conditions they see it. 7. The Visibility properties enable you to restrict what process participants see in the runtime Heritage Coach. From the Default Visibility list. Procedure 1. the input text box is shown in a different color and you are not able to end the task successfully until you supply the required input. Doing so allows you to change the default Visibility properties. 4. Click the Heritage Coach control that you want to make a required input area. Click the Visibility option in the properties. 3. 5. Optional: Clear the Override Parent Visibility check box to set the Visibility properties back to read-only mode. input controls are visible to and can be edited by everyone. By default. Run the service to test the runtime Heritage Coach. If you leave the required input text box empty and then click Next. select the Required (full access) for everyone option. Select the Override Parent Visibility check box. 6. Parent topic:Configuring Heritage Coach controls Related information: Controlling field and other formatting in heritage coaches 726 .Making an input control a required field in a Heritage Coach You can make input mandatory by configuring a Heritage Coach control as described in this procedure. 2. Open the service that contains the Heritage Coach that you want to work with and then click the Coaches tab. Open the service that contains the Heritage Coach that you want to work with and then click the Coaches tab. 2. select the ==(equals) operator. 4. the Heritage Coach displays an input field where the employee can indicate the percentage of his pay to contribute to the plan. Entries for the Value and Display Text fields Value true false defer Display Text Yes No Decide at a later date 6. 727 . the employee can defer the decision to a later date. This creates a new override condition. type Do you want to contribute? in the Label text box. Drag a List control from the palette onto the design area. Under the Control Dependent Visibility section. With the Add button. Doing so allows you to change the default Visibility properties. 3. create three Value-Display pairs. The Heritage Coach in this example is used by new employees to specify the benefits that they want. 14. From the Control list. From the Default Visibility drop-down list. Select the Override Parent Visibility check box. In the properties for the control. Drag a Text control from the palette onto the design area. 8. 10. Or. In the properties for the control. 7. Click the Presentation option in the properties. About this task The following procedure illustrates how to create a control that is displayed only when a related control is set to a specific value. 9. select the Hidden (no access) for everyone option. type 401K Contribution % in the Label text box. Procedure 1. specify the coach control the input value of which is to determine if the selected control is displayed to participants when the service runs. one for each list item option as shown in the following table:Table 1.Displaying a control based on the input value of another control in a Heritage Coach You can create a control that is displayed only when a related control is set to a specific value. 11. Under the Manual Data section. 5. Click the Depends on Control button. From the Operator list. In this example. 13. the control is the Do you want to contribute? List control. select the Required (full access) option from the Visibility drop-down list. If the employee decides to participate in a 401K plan. Click the Visibility option in the properties. click the Add button. 12. 'defer'}". Depending on the selection list choice. Drag a Date Selector control from the palette onto the design area. The Date Selector will be displayed if either of these options is selected. This is the value that you assigned to the Yes list option in step 5. Click Visibility. These are the values that you assigned to the Yes and Decide at a later date list options in step 5. In the Value text box. 18. 17. 20. In the properties for the control. 21. type Date in the Label text box. Parent topic:Configuring Heritage Coach controls Related information: Displaying a control to a specific group in a heritage coach 728 . 16.15. select the in operator. Save the Heritage Coach and then run the service to see how the Input and Date Selector controls are hidden and then shown according to the visibility rules you have specified. From the Operator list. type "{'true'. this can be the date of contribution or the date until a contribution decision is deferred. In the Value text box. 19. type true. and repeat the steps above to make the Date Selector dependent on the control Do you want to contribute?. Click the Visibility option in the properties. About this task The following procedure describes how to display a Heritage Coach control to only those users who are members of a particular group. 4. Click the Depends on Group button. select the visibility option that you want for this group from the Visibility drop-down list. Under Group Dependent Visibility.Displaying a control to a specific group in a Heritage Coach Learn how to display a control to only those users who are members of a particular group. 5. Click the Override Parent Visibility check box to enable it. In this context a group is equivalent to a team. See Creating a team for more information. Under Group Dependent Visibility. 2. Parent topic:Configuring Heritage Coach controls 729 . Save the Heritage Coach and then run the service to see how the control is hidden and then shown according to the visibility rules you have specified. Procedure 1. 9. Click the Heritage Coach control that you want to display to only those members of a group. Open the service that contains the Heritage Coach that you want to work with and then click the Coaches tab. 6. 7. Doing so allows you to change the default Visibility properties. From the Default Visibility drop-down list. 8. select the Hidden (no access) for everyone option. This creates a new override condition. 3. click the Select button to choose the group that you want. Changing the visibility of a Heritage coach control Use a custom script to override the default visibility rules for a particular control in a Heritage coach. Open the service that contains the Heritage Coach to work with.local. if(tw. Click the Visibility option in the properties. 730 . Values returned for custom visibility Value "NONE" "READ" "FULL" "REQUIRED" Result Hidden Disabled Editable Required The following script causes the runtime engine to determine if user input is required:var customVisibility. 4. and so return statements are required. Click the Variables tab and add the private variables that you need for the custom script. For custom visibility using server-side JavaScript. select the Hidden (no access) for everyone option. 8. Procedure 1.enabled) { if(tw. The following example uses a server-side JavaScript function. 2. } } else { customVisibility = "NONE".required) { customVisibility = "REQUIRED". 6. 7. and required.visible) { if(tw. In the Custom Visibility section. add Boolean variables named visible . and how the values of those variables determines visibility of the selected control. For this example. 3. From the Default Visibility list.local. return one of the following values (must be in upper case): Table 1. enabled . About this task The following procedure illustrates how you can create private variables to use in a custom visibility script. Click the Heritage Coach control for which you want to add visibility control. } } else { customVisibility = "READ". Click the Override Parent Visibility check box to enable it.local. 5. enter the JavaScript rule to control visibility. 9. Click the Coaches tab. Click the Custom Script button. Doing so allows you to change the default visibility properties. You can set default values for the variables (that you added in step 2) and then run the service to test the script. the control can be edited.local. 10. If user input is not required. Parent topic:Configuring Heritage Coach controls Related information: Validating user input for heritage coach button controls 731 . but it is not required.visible is false. the control is not displayed to the user.} return customVisibility. If the value of tw. If multiple buttons are included in the control. under Buttons. you can add client-side validation scripts for button controls. 4. click the button that needs the validation script. return false. 2. Parent topic:Configuring Heritage Coach controls 732 . In the design area. clicking the button discards any changes to variable values. To do this. and moves the token to the next step in the flow. use the control ID of each required control. an OK or Submit button that runs a validation script on the user input is accompanied by a Cancel button which discards the user input. 5. } else { alert( "Check the checkbox"). Open the service that contains the Heritage Coach that you want to work with and then click the Coaches tab.getElementById("checkbox0_checkbox"). type the JavaScript to validate that the required controls have been set and contain values as expected. 3. When Is Cancel is selected for a button. If not. click to select the control for which you want to add a validation script. Validation scripts ensure that users provide all required input. The following example is client-side JavaScript that uses the default controls included when you add a new Heritage Coach to a service. the script provides the appropriate feedback to prompt users for the required information. What to do next In many cases. The following validation script checks to ensure that the check box is enabled (set to true). About this task When building Heritage Coaches in IBM® Business Process Manager. Procedure 1. If not. the user is prompted to check it before proceeding by clicking OK. } 6. Click the Presentation option in the properties.checked == true ){ return true.Validating user input Add validation scripts for button controls in Heritage coaches to ensure that users provide all required input. if ( document. In the text box under the Validation Script section. Save the Heritage Coach and then run the service to test the script. . you can add field formatting capability to Input Text and Output Text controls.Using pre-defined formats in Heritage Coach Controls Choose from the available predefined character formats for your Heritage Coach controls. . . When building Heritage Coaches. . .Aligning buttons in a Heritage Coach You can specify the alignment of buttons in a Button Group control as described in this procedure. as described in this procedure. The pre-defined field formatting available with Heritage Coaches includes standards such as US social security number.Controlling field and other formatting in Heritage Coaches Learn how to add field formatting capability to Input Text and Output Text controls and align button controls.Aligning check boxes and radio buttons in a Heritage Coach You can specify the horizontal and vertical alignment of check boxes and radio buttons. see the following: . . To learn more. and other standards. Parent topic:Configuring Heritage Coach controls 733 . . the Date Selector control in a Heritage Coach uses the Gregorian calendar.Using formatting with variables in a Heritage Coach Learn how to apply formatting to a Heritage Coach control that is bound to a variable.Heritage Coaches: Configuring a Hebrew or Islamic calendar By default.Using formatting with language localization resources in a Heritage Coach You can apply formatting to a Heritage Coach control that is bound to a localization resource as described in this procedure. You can configure the control to use the Hebrew or Islamic (Hijri) calendar.Using characters to apply custom numeric formatting in a Heritage Coach Learn how to apply numeric formatting to a control for integers and decimals. currency in dollars and Euros.Adding custom format types in a Heritage Coach You can modify the predefined character formats for text controls or create additional formats. You can also use customized formats and apply formats to variables and localization resources that are bound to Heritage Coach controls. ###. the value is formatted to $123.## € Currency: € ###.## Integer: ###.## Currency: ###.###. Click the Presentation option in the properties.## US phone: (###) 000-0000 US SSN: 000-00-0000 Example Enter the value 123456789 . the values typed into the control are automatically formatted as shown in the preceding examples.###. Click the Heritage Coach control for which you want to add formatting. If a user enters only non-numeric characters. When you run the service that contains the Heritage Coach.789 Enter the value 123456789 .789 Enter the value 123456789 . the value is formatted to 123-45-6789 5.789 Enter the value 5555555555 . the value is formatted to 123.###.456. those characters are removed. the value is formatted to €123.Using pre-defined formats in Heritage Coach Controls Choose from the available predefined character formats for your Heritage Coach controls. the value is formatted to (555) 555-5555 Enter the value 123456789 .456.456. no formatting is applied.###. click the Select button next to the Format field and choose the format that you want:Table 1.###. Open the service that contains the Heritage Coach that you want to work with and then click the Coaches tab.456. the value is formatted to 123. 2.###.### Decimal: ###. Parent topic:Controlling field and other formatting in Heritage Coaches Related information: Adding custom format types in a heritage coach Using characters to apply custom numeric formatting in a heritage coach 734 . About this task The following procedure describes how to choose from the available predefined character formats. Input required for the Format options Option Currency: $ ###.789 Enter the value 123456789 . 3. Under Widget Style. If a user enters non-numeric characters.###.###. 4.456.789€ Enter the value 123456789 . Save your changes. the value is formatted to 123. Procedure 1. 735 . If there is no digit in this position. Under Widget Style. For example. 3.# (placeholder for two digits and the tenths decimal position) Results Since no decimal placeholder is specified. For example. . Follow these steps to use characters to apply custom numeric formatting: Procedure 1. The following characters are available: Table 2. you'll get the described results: Table 1. the value 34. 2.57 would be rounded up to 34. type the characters that you want to use as placeholders in the Format field. 4. and decimals greater than or equal to five are rounded up.2 into the control.Using characters to apply custom numeric formatting in a Heritage Coach Learn how to apply numeric formatting to a control for integers and decimals.2 . then nothing is stored in the output. and the value 34. Characters available to use as placeholders Character # Name Digit placeholder 736 Description A digit is copied into output. Click the Presentation option in the properties. if a user enters the value 34. About this task If you want to apply numeric formatting to a control for integers and decimals. For additional decimal positions typed in to the control during run time. the value is rounded up to 35 . the # character acts as a digit placeholder. Click the Heritage Coach control for which you want to add formatting. So if you type the following placeholders into the Format field in the Presentation properties for a control. you are not required to select one of the pre-defined formats. For example. values entered into the control during run time are rounded up to the next integer. Format placeholders and corresponding results Format placeholder ## (placeholder for two digits) ##. decimals less than five are rounded down. Instead you can manually enter custom formatting characters into the Format field.6 .24 would be rounded down to 34. Open the service that contains the Heritage Coach that you want to work with and then click the Coaches tab. The first . a 0 is inserted into this position. If there is no digit in this position. a " " (space symbol) is inserted into this position. A digit is copied into output. If there is no digit in this position.0 Zero placeholder ? Padding placeholder . . Decimal separator 737 A digit is copied into output. The actual character used as the decimal separator is determined by user locale settings. character (period) in the format string determines the location of the decimal separator in the formatted value. if the format string contains a .. character between two digit placeholders (0 or #) and to the left of the decimal point if one is present. characters multiplied by 1000 before it is formatted. For example. The actual character used as the decimal separator in the result string is determined by user locale settings. will represent 100 million as simply 100. First. The presence of a % character in a format string causes a number to be multiplied by 100 before it is formatted. then the number will be divided by the number of . then the output will have thousand separators inserted between each group of three digits to the left of the decimal separator. The appropriate symbol is inserted into the number itself at the location where the % appears in the format string. characters immediately to the left of the decimal point. character to indicate scaling does not include thousand separators in the formatted number. ... Thus. if the format string contains one or more . Second. Thousand separator % Percentage 738 The .##0. the format string 0. to scale a number by 1 million and insert thousand separators you would use the format string: #. character (comma) serves two purposes. Use of the . e . 5. e or eformats indicate that a sign character should only precede negative exponents. E+ .are present in the format string and are followed immediately by at least one 0 character. negative. Parent topic:Controlling field and other formatting in Heritage Coaches 739 . The E .. E. E. Save your changes.E0 E+0 E-0 e0 e+0 e-0 Scientific notation . The number of 0 characters following the scientific notation indicator determines the minimum number of digits to output for the exponent. All other characters are copied to the result string as literals in the position where they appear. Section separator Other All other characters If any of the strings E .. then the number is formatted using scientific notation with an E or e inserted between the number and the exponent. and zero numbers in the format string. The . character (semicolon) is used to separate sections for positive. The E+ and e+ formats indicate that a sign character (plus or minus) should always precede the exponent. e+ or e. The predefined character formats for Input Text and Output Text controls are defined by the <formatting-templates> section in the PROFILE_HOME \config\cells\cell_name\nodes\node_name\servers\server_name\processcenter\config\system\99Local.###.xml file.Note: If the 100Custom.xml file.Adding custom format types in a Heritage Coach You can modify the predefined character formats for text controls or create additional formats.###.##" /> <formatting-template comment="US phone" template="(###) 000-0000" /> <formatting-template comment="US SSN" template="000-00-0000" /> </formatting-templates> Note: If you add or modify formats in your development environment by altering settings for the Process Center server.###.###. create it as described in The 99Local.###" /> <formatting-template comment="Decimal" template="###. You can define additional formats as needed in the 100Custom.xml configuration files.##" /> <formatting-template comment="Currency" template="###.###.###.###.xml file.###. <formatting-templates> <formatting-template comment="Currency" template="$ ###. copy the <formattingtemplates> section shown below and paste it into the 100Custom.##" /> <formatting-template comment="Integer" template="###.## €" /> <formatting-template comment="Currency" template="€ ###.xml and 100Custom. To modify the formats or create additional formats.###. be sure to make the same changes for each Process Server in your runtime environments. Parent topic:Controlling field and other formatting in Heritage Coaches 740 .xml does not yet exist. when you run the service the Heritage Coach control is populated with the value of the variable. Heritage Coach will strip out characters such as '. Parent topic:Controlling field and other formatting in Heritage Coaches Related information: Using formatting with language localization resources in a heritage coach 741 .000. For example. if the US currency (dollars/cents) format is selected for the Heritage Coach control.'.local.Using formatting with variables in a Heritage Coach Learn how to apply formatting to a Heritage Coach control that is bound to a variable.amount with a default value of 251000. To resolve this issue. All input values are treated as numbers. If you create a service that includes a decimal variable named tw. you could create a private variable with a Decimal data type and bind that to the text control. Note: When the input text control is bound to a variable with a String data type and you specify a predefined character format. and the value is formatted to $251. you can still specify the format in which the value is displayed even though the value that the control displays during run time is determined by the value of the variable to which the control is bound.amount variable.0 and you bind a Heritage Coach control to the tw. You can apply formatting to a Heritage Coach control that is bound to a variable. even if they are bound to string variables.' and '.local.00. Open a service that includes several variables. Save your changes.24.##. 3. Create a Heritage Coach that includes an input text control named Time. Then run the BPD that contains the service and run the task from the Process Portal. Optional: You can test the binding. 5. which is the standard format used to represent time in the majority of countries.LocalizedFormats. The value of Default Locale is ##:##:##. The localization resource for this example (named Localized Formats) includes a localization key named time. About this task You can apply formatting to a Heritage Coach control that is bound to a localization resource. Localized Formats) that you want to link to the service variables as a resource bundle. The value of the Sweden locale is ##. which is the standard format for Swedish time. which conforms to the formatting that you specified. Then bind the formatting of the control to the localization resource bundle and localization key by typing <#= tw.Using formatting with language localization resources in a Heritage Coach You can apply formatting to a Heritage Coach control that is bound to a localization resource as described in this procedure. Parent topic:Controlling field and other formatting in Heritage Coaches 742 .resource. change the interface language to svenska in IBM® Process Portal preferences. the value should be formatted to 18. To test the binding. Procedure 1.00 .time #> into the Format field. When a you enter a 6-digit value such as 182400 into the Time field.##. Click the Link Localization button and select the localization resource (in this example. 2. which contains two locales: Default Locale and Sweden. 4. and click the Variables tab. Run the Coach. Open the Heritage Coach. To add a Heritage Coach. In the Diagram page.Heritage Coaches: Configuring a Hebrew or Islamic calendar By default. 6. You can configure the control to use the Hebrew or Islamic (Hijri) calendar. 7. Select Hebrew or Islamic in the National Calendars list. instead of the Gregorian calendar. 4. drag a Date Selection control onto the editor. 2. Procedure 1. Open a Heritage Human service. From the Controls section of the palette. Open the Process Designer desktop editor. the Date Selector control in a Heritage Coach uses the Gregorian calendar. The Hebrew or Islamic calendar is displayed in the date selector. 8. switch to the Presentation tab. 9. For more information. see Setting preferences in Process Portal Parent topic:Controlling field and other formatting in Heritage Coaches 743 . You can also change a preference in Process Portal to display the Hebrew or Islamic calendar. add or select a Heritage Coach. In the Properties view. 5. scroll to the bottom of the palette. 3. About this task You can choose to display your calendar in the Hebrew or Islamic format calendars by configuring the Date Selector control. In the design area. 2. Parent topic:Controlling field and other formatting in Heritage Coaches Related information: Aligning check boxes and radio buttons Setting column widths in a heritage coach Setting the number of columns in a heritage coach 744 .Aligning buttons in a Heritage Coach You can specify the alignment of buttons in a Button Group control as described in this procedure. Select the alignment (Left. 4. About this task When building Heritage Coaches. 3. Open the service that contains the Heritage Coach that you want to work with and then click the Coaches tab. Center. Click the Preview tab to see how the buttons will be displayed when you run the service. or Right) for the Button Group from the dropdown list. 5. Click the Presentation option in the properties. you can specify the alignment of buttons in a Button Group control as described in the following procedure: Procedure 1. click to select the Button Group control that you want to align. 6. From the Widget Type drop-down list. Parent topic:Controlling field and other formatting in Heritage Coaches Related information: Setting column widths in a heritage coach Setting the number of columns in a heritage coach 745 . Note: Single-selection List controls that use radio buttons provide the same alignment options in the Presentation properties. Open the service that contains the Heritage Coach that you want to work with and then click the Coaches tab. Click the Preview tab to see how the buttons will be displayed when you run the service. In the design area. 3. From the Orientation drop-down list. Click the Presentation option in the properties. you can specify the horizontal and vertical alignment of check boxes and radio buttons. 5. About this task When building Heritage Coaches. click to select the Dual List control that you want to align. select Vertical or Horizontal. as described in the following procedure. 2.Aligning check boxes and radio buttons in a Heritage Coach You can specify the horizontal and vertical alignment of check boxes and radio buttons. 4. Procedure 1. as described in this procedure. select Multiple Check Boxes . Choosing the type of documents to attach to a Heritage Coach Before attaching documents to a Heritage Coach. . .Attaching ECM documents to a Heritage Coach Learn how to configure the Document Attachment Heritage Coach control to display only those ECM documents that match properties that you set.Attaching IBM Business Process Manager documents to a Heritage Coach You can configure the Document Attachment Heritage Coach control to display documents that match properties that you set.Adding documents and reports to Heritage Coaches You can upload documents and embed reports for display in Heritage Coaches. you need to establish the type of documents that you want to display and upload using the Document Attachment control. Parent topic:Building Heritage Coaches 746 . You can also configure the control to enable process participants to upload additional documents.Embedding documents in a Heritage Coach You can configure the Document Viewer Heritage Coach control to display a single document or one of several documents that process participants choose from a list. . .Embedding IBM Business Process Manager reports in a Heritage Coach Learn how to embed reports in Heritage Coaches. . If you selected IBM Content Integrator for the Connection Type.Choosing the type of documents to attach to a Heritage Coach Before attaching documents to a Heritage Coach. 4.IBM BPM documents . Drag a Document Attachment control from the palette onto the design area. 3.IBM Content Integrator 5. Click the Connection option in the properties. complete the following steps: A. you need to establish the type of documents that you want to display and upload using the Document Attachment control. Procedure The following steps describe how to establish which type of documents you want to display and upload using the Document Attachment control: 1. While the Document Attachment control is selected. Before you can access documents from an ECM repository using the Document Attachment control. B. IBM Content Integrator SOA web services must be deployed on an application server. 2. See Deploying > Deploying SOA Web Services in the IBM Content Integrator Information Center. To use the Document Attachment control to access documents from an ECM repository. click the Document Attachment option in the properties if not already selected. Provide the following information: Table 1. IBM BPM documents are any documents that your users can access by browsing their file system or via a URL. and then click the Coaches tab. select a Connection Type from the drop-down list: . Input required for connection properties Property Description 747 . In the Behavior section. Before you begin The Document Attachment control works with IBM® Business Process Manager documents or documents stored in an Enterprise Content Management (ECM) repository. Open the service that contains the Heritage Coach that you want to work with. enabling users to access documents from FileNet® P8 Content Manager and IBM Content Manager. The IBM Content Integrator Information Center provides information about the WAR file that you can use for deployment and instructions for configuring the WAR file. you can configure the control to work with IBM Content Integrator Enterprise Edition. User name required to log in to the ECM repository. Parent topic:Adding documents and reports to Heritage Coaches Related information: Attaching IBM Business Process Manager documents to a heritage coach 748 . Select the environment variable that contains the name of the IBM Content Integrator connector that you want to use to access the ECM repository. Password required to log in to ECM repository. if your server configuration is named iciService. The name of this environment variable is the name of the target IBM Content Integrator server configuration with a _connectorName suffix. you can attach documents to the Heritage Coach for which you configured the connection type. The name of this environment variable is the name of the target IBM Content Integrator server configuration.IBM Content Integrator (ICI) Web Service URL Select the environment variable that contains the root URL of the deployed application (SOA web services). By configuring the control. the connector name will be contained in an environment variable named iciService_connectorName. For example. Repository ID User name Password What to do next Configure the control to display and upload documents for your connection type. See Adding a server configuration for information on defining an IBM Content Integrator server configuration. See Adding a server configuration for information on defining an IBM Content Integrator server configuration. 749 . Important: If you disable this check box. when disabled. In addition to displaying documents. Under Display Documents. be sure to set properties that clearly identify the documents to display. About this task When you add the Document Attachment control to a Heritage Coach.Attaching IBM Business Process Manager documents to a Heritage Coach You can configure the Document Attachment Heritage Coach control to display documents that match properties that you set. When not selected. While the Document Attachment control is selected. Open the service that contains the Heritage Coach that you want to work with and then click the Coaches tab. you can limit the displayed documents to only those documents uploaded during the execution of the current process instance. The check box is selected by default. If you do not. select or clear the Associated Process Instance check box. BPD. you can also configure the Document Attachment control to enable users to upload additional documents. the control displays all documents. Plus. 3. You can also configure the control to enable process participants to upload additional documents. Drag a Document Attachment control from the palette onto the design area or click to select an existing control. You can configure the control to display only those documents that match properties that you set. 4. If you cleared the Associated Process Instance check box. or process application from which they originated. 5. 2. For example. Procedure The following procedure describes how to display a list of IBM BPM documents in your Heritage Coach using the Document Attachment control: 1. you can configure the control to display only those documents associated with a specific client or customer. regardless of instance. choose one of the following options: Option Description 750 . documents that were previously uploaded during completion of an IBM® BPM task are displayed. click the Presentation option in the properties. the number of displayed documents could be much larger than expected or than is useful. This setting causes the control to display only those documents uploaded in previous steps of the running process instance. Click the Add button to add the properties that will determine which documents are displayed. Each property should have a name and a value. A. Click the Add button to add the properties that will determine which documents are displayed. The check box is selected by default.All Properties Displays only documents that match all properties that you add. For example. C. While the Document Attachment control is selected. you must run the BPD so that the current control has access to documents to display. you can run the service to test the configuration. 6. . and then click OK to upload the document. When the service runs. if you want to display documents that users uploaded in an earlier step. . For example. complete the following steps. you might add a property with a name of client and a value of smith. clear the Enabled check box under Upload Documents. provide a title for the document. If you want to display documents from a different process. examine the Heritage Coach for the earlier step to see the properties established for those uploaded documents.If not. If you do not want to configure this control for document uploads.If the same service enables users to upload documents in a preceding step. Verify the Enabled check box under Upload Documents is selected. To configure the same Document Attachment control to enable document uploads. Drag a Document Attachment control from the palette onto the design area or click a preexisting Document Attachment control to select it. Save the Heritage Coach and then run the service or BPD to test your configuration. you might add a property with a name of client and a value of smith. Note: The document properties that you add should match the properties set for uploaded documents. 751 . This setting causes the control to display an Add Document button. Each property should have a name and a value. Open the service that contains the Heritage Coach that you want to work with and then click the Coaches tab. B. For example. Any Properties Displays documents that match any of the properties that you add. the user can click the Add Document button and then use the fields provided to browse for the URL or file that they want to upload. The user can upload multiple documents using the control. click the Presentation option in the properties. 7. D. open the BPD and its services and then examine the properties established for those uploaded documents. work with documents in the Process Portal. For example. type the JavaScript for the default in the Default Name text box. The properties that you add to uploaded documents enhance the Display Documents capability of the control. G. but want the user to be able to change the default. you might add a property with a name of client and a value of smith. All properties that you add to uploaded documents can be used to select the documents to display. Each property should have a name and a value. type <#= tw. F. click the User Editable check box to enable it. If you want to supply a default name for all documents that the user uploads. Click the Add Properties check box to enable it if you want to add properties to uploaded documents. Parent topic:Adding documents and reports to Heritage Coaches Related information: Attaching ECM documents to a heritage coach 752 . If you supply a default name. What to do next To see how these controls appear to users. For example. Save the Heritage Coach and then run the service or BPD to test your configuration. Then click the Add button to add the properties that you want.user_fullName #> to make the current user name the default name for uploaded documents.E.system. Or. Important: The filters that you specify must match the actual property values in the ECM repository. simply enter an asterisk to retrieve documents for all properties: * . Click All Properties or Any Properties. and click the Add button. In the Item Class Name field. In addition to displaying documents. you can also configure the Document Attachment control to enable users to upload additional documents to the ECM repository. . click the Presentation option in the properties. After the connection is established. You should configure the control to display only those documents that match properties that you set. 6. you can configure the control to display only those documents associated with a specific client or customer. 4. click the property name and then click the Remove button. This enables you to choose the properties to use to determine the documents to display. For example.If you select All Properties.Attaching ECM documents to a Heritage Coach Learn how to configure the Document Attachment Heritage Coach control to display only those ECM documents that match properties that you set. Procedure The following procedure describes how to display a list of ECM documents in your Heritage Coach using the Document Attachment control: 1. 3. All properties that exist for the document type that you specify are displayed. Before you begin When you add the Document Attachment control to a Heritage Coach. You can also use an *(asterisk) as a wildcard when establishing filters. you need to establish a connection to the repository as described in Choosing the type of documents to attach to a heritage coach. For example. Open the service that contains the Heritage Coach that you want to work with and then click the Coaches tab. documents must match all properties that you add 753 . . Determine whether you want to remove or filter any of the listed properties: . if one of the properties for a document type is ClientIndustry . enter the name of the document type that you want to retrieve from the ECM repository. you can use the Document Attachment Heritage Coach control as described in the following procedure. 5. 2. enter the following text to filter for all properties that begin with auto : auto* . you could limit the results to a specific industry by entering the following text in the Filter Value column: automotive .To filter for particular properties. While the Document Attachment control is selected. enter a value in the Filter Value column. For example. documents from the connected ECM repository can be displayed. Before you can attach documents stored in an Enterprise Content Management (ECM) repository to a Heritage Coach.To remove unwanted properties. Drag a Document Attachment control from the palette onto the design area or click to select an existing Document Attachment control. For example. Drag a Document Attachment control from the palette onto the design area or click a preexisting Document Attachment control to select it. 9.If you select Any Properties. If you supply a default name. In the Display table. work with documents in the Process Portal. D. 8. Parent topic:Adding documents and reports to Heritage Coaches 754 . 7. but want the user to be able to change the default. type the JavaScript for the default in the Default Name text box. the Enabled check box under Upload Documents is selected. What to do next To see how these controls appear to users.If you want to configure the Document Attachment control to enable document uploads. Save the Heritage Coach and then run the service or BPD to test your configuration. enter the value that you want the Heritage Coach interface to use as the label for each property.If you do not want to configure the Document Attachment control to enable document uploads. E. click the User Editable check box to enable it. F. Then click the Add button to add the properties that you want. When the service runs. Open the service that contains the Heritage Coach that you want to work with and then click the Coaches tab.to be displayed. The user can upload multiple documents to the connected ECM repository using the control. Choose one of the following options to configure whether users can upload documents to the connected ECM repository using the Document Attachment control: . While the Document Attachment control is selected. clear the Enabled check box under Upload Documents. G. Click the Add Properties check box to enable it if you want to add properties to uploaded documents. This setting causes the control to display an Add Document button. the user can click the Add Document button and then use the fields provided to browse for the file that they want to upload to the ECM repository. C. By default. If you want to supply a default name for all documents that the user uploads. and then click OK to upload the document. B. provide a title for the document.system. and enter a value in the Display Value column for each property. . click the Presentation option in the properties. . the control displays them.user_fullName #> to make the current user name the default name for uploaded documents. if documents match any one of the properties that you specify. Save the Heritage Coach and then run the service or BPD to test your configuration. complete the following steps: A. Each property should have a name and a value. type <#= tw. For the Control field. Click the Presentation option in the properties. it is displayed in the viewer. IBM Content Integrator. Procedure The following procedure describes how to configure the Document Viewer Heritage Coach control to enable users to display a document from a list and configure the Document Viewer Heritage Coach control to display a single document: 1. enabling users to access documents from FileNet P8 Content Manager and Content Manager. 4. or to display a single document.Embedding documents in a Heritage Coach You can configure the Document Viewer Heritage Coach control to display a single document or one of several documents that process participants choose from a list. choose Document Attachment from the drop-down list. . You can configure the Document Viewer Heritage Coach control to display one of several documents that the user chooses from a list. The Heritage Coach control works with IBM Content Integrator Enterprise Edition. C. Save the Heritage Coach and then run the service or BPD to test your configuration. 7. choose None from the drop-down list. Select the Connection Type from the drop-down list: IBM BPM documents. F. 3. you can configure the Document Viewer Heritage Coach control to display a single document by choosing the connection type and then completing the configuration for the chosen connection type. About this task The Document Viewer Heritage Coach control enables you to display the contents of an Enterprise Content Management (ECM) or IBM® Business Process Manager document in a separate frame directly within a Heritage Coach. choose the Document Attachment control currently included in your Heritage Coach that you want to associate with this Document Viewer control. B. Configure the Document Viewer Heritage Coach control to display a single document by choosing the connection type: A. or URL. E. Open the service that contains the Heritage Coach that you want to work with and then click the Coaches tab. After testing the configuration. Drag a Document Viewer control from the palette onto the design area or click a preexisting Document Viewer control to select it. Open the service that contains the Heritage Coach that you want to work with and then click the Coaches tab. D. 2. Drag a Document Viewer control from the palette onto the design area or click a preexisting Document Viewer control to select it. For the Association field. Click the Document Viewer option in the properties. 6. 5. For the Association field. The Document Attachment control establishes the list of documents from which the user can choose.IBM BPM documents 755 . When a user selects one of the documents. Click the Document Viewer option in the properties. For the First Document Matching field.. if a document matches any one of the properties that you specify. If the same service enables users to upload documents in a preceding step. you can run the service to test the configuration.If you selected IBM BPM documents. BPD. If not already selected. . The check box is selected by default. Click the Add button to add the properties that will determine which document is displayed. complete the following steps: A. regardless of instance. . See Deploying > Deploying SOA Web Services in the IBM Content Integrator Information Center. the number of displayed documents could be much larger than expected or than is useful. Provide the following information for the IBM Content Integrator connection: Note: Before you can access documents from an ECM repository using the Document Viewer control. If not. Input required for the IBM Content Integrator connection 756 . IBM Content Integrator SOA web services must be deployed on an application server.IBM Content Integrator . Each property should have a name and a value. open the BPD and its services and then examine the properties established for those uploaded documents. Important: If you disable this check box. Note: The document properties that you add should match the properties set for uploaded documents. select or clear the Associated Process Instance check box. documents must match all properties that you add to be displayed. you must run the BPD so that the current control has access to documents to display. Table 1. complete the following steps: A. click All Properties or Any Properties. click the Presentation option in the properties. E. This setting causes the control to display only those documents uploaded in previous steps of the running process instance. The Document Viewer control displays the first document that matches the properties that you choose. if you want to display a document that the users uploaded in an earlier step. B.If you selected IBM Content Integrator. B.If you select Any Properties. Complete the configuration for the connection type you selected: . If you want to display a document from a different process. . If you do not. examine the Heritage Coach for the earlier step to see the properties established for those uploaded documents. For example. Under Display Documents. be sure to set properties that clearly identify the documents to display.URL 8. If not already selected. C. the control displays all documents. When not selected.If you select All Properties. or process application from which they originated. D. The IBM Content Integrator Information Center provides information about the WAR file that you can use for deployment and instructions for configuring the WAR file. Save the Heritage Coach and then run the service or BPD to test your configuration. click the Presentation option in the properties. you might add a property with a name of client and a value of smith. the control displays it. For example. when disabled. See Setting environment variables to learn how to define an environment variable of type ICI web service URL. click All Properties or Any Properties. the document must match all properties that you add to be displayed. The control displays the first document that matches the properties that you choose. if one of the properties for a document type is ClientIndustry . Save the Heritage Coach and then run the service or BPD to test your configuration. All properties that exist for the document type that you specify are displayed. D. Optional: Limit the results by entering filterable text in the Filter Value column. complete the following steps: 757 .Value IBM Content Integrator (ICI) web service URL Description Select the environment variable that contains the root URL of the deployed application (SOA web services).If you select All Properties. Note: The filters that you specify must match the actual property values in the ECM repository.If you selected URL as the connection type for the Document Viewer control. . G. F. This enables you to choose the properties to use to determine the document to display. if a document matches any one of the properties that you specify. Repository ID User name Password C. . User name required to log in to the ECM repository. the control displays it. In the Item Class Name field. E. you could limit the results to a specific industry by entering the following text in the Filter Value column: automotive . enter the name of the document type that you want to retrieve from the ECM repository.If you select Any Properties. For example. . For the First Document Matching field. Select the environment variable that contains the name of the IBM Content Integrator connector that you want to use to access the ECM repository. Password required to log in to ECM repository. and click the Add button. To remove unwanted properties. click the property name and then click the Remove button. See Setting environment variables to learn how to define an environment variable of type ICI Connector Name. A. If not already selected. B. click the Presentation option in the properties. Parent topic:Adding documents and reports to Heritage Coaches Related information: Embedding IBM Business Process Manager reports in a heritage coach 758 . In the URL field. C. Save the Heritage Coach and then run the service or BPD to test your configuration. type the location of the document that you want to display. Procedure To embed an IBM BPM report in a Heritage Coach: 1. 4. click the Add button to choose parameters by which to filter the report results. Open the service that contains the Heritage Coach that you want to work with and then click the Coaches tab. In the Filter Parameters panel. In the Common area. The data available in an IBM BPM report can help process participants make decisions regarding tasks and task assignments. 3. you may want to embed IBM BPM reports in your Heritage Coaches so that users can make informed decisions with the business data that they need directly available. For this reason. 2. About this task IBM® BPM reports provide valuable information about your business processes. Drag a Report control from the palette onto the design area.Embedding IBM Business Process Manager reports in a Heritage Coach Learn how to embed reports in Heritage Coaches. you can provide an unique control ID for the report and adjust the number of rows and columns that the report spans within the Coach. you can provide documentation for the report and add a label. use the drop-down list to choose the report page that you want to display in your Heritage Coach. you can click New to create a new report. 7. In the Page to Display field. Save the Heritage Coach and the run the service to ensure the report is displayed properly. click the Presentation option in the properties. Under Report Settings. In the Behavior area. 8. Provide the appropriate value in the Value column. 9. If the report does not yet exist. click the Select button to choose the IBM BPM report that you want to embed. 5. While the Report control is selected. 6. Specific instructions for creating and configuring reports are provided in the related information. Click the Report option in the properties. Parent topic:Adding documents and reports to Heritage Coaches 759 . . override CSS styles.Enhancing interface layout using custom attributes You can add custom attributes to Heritage Coach sections and controls to enhance the layout of the interfaces that you create for users. . Read the following topics to learn more about customizing Heritage Coaches: .Adding custom images to a Heritage Coach Heritage Coaches can include corporate branding and other graphic customizations. In a typical IBM® Business Process Manager deployment. or perform other customization tasks when creating Heritage Coaches.Specifying an XSL transform override for a Heritage Coach You can use your own .Customizing Heritage Coaches You can include custom images. you can meet your customization requirements by configuring the presentation and visibility properties available in the Designer interface.Setting the length of input text fields Overriding CSS styles in a Heritage Coach control also enables you to set the maximum length (in pixels) for an Input Text control.xsl file to customize an entire Heritage Coach. . Heritage Coaches are highly customized to render a particular look and feel. In many cases. For example. you should have a good understanding of how they work to ensure that your customization produces the results you want. .Specifying a custom CSS for a Heritage Coach You can use your own Cascading Style Sheet (CSS) to customize an entire Heritage Coach. . Parent topic:Building Heritage Coaches Related information: Configuring heritage coach controls Adding sections to a heritage coach and controlling the layout 760 . you may want to customize Heritage Coaches to use corporate logos and colors. .How Heritage Coaches work Before you customize Heritage Coaches.Overriding CSS styles for selected controls and fields You can override Cascading Style Sheet (CSS) styles to customize the appearance of a Heritage Coach. you should have a good understanding of how they work to ensure that your customization produces the results you want.css in the following image) instructs the client how to render the HTML output. You can view the XML while you're building a Heritage Coach by clicking the Code View icon in the toolbar. As you drag sections and controls to a Heritage Coach. Both client-side and server-side JavaScript is used to render Heritage Coaches. JavaScript provides the methods and functions that implement runtime Heritage Coach features. A Developer generates the XML definition of a Heritage Coach by generating files. The runtime rendering of a Heritage Coach involves the following key technologies: Table 1. and coach_designer. The following image shows how Heritage Coaches are generated: 761 . The Cascading Style Sheet (coach_designer. The XLS renders a server-side-scriptlet that is run to generate the HTML.js. Those files are then rendered. The client (web browser) renders the HTML that the Heritage Coach generates from its XML definition through XSLT processing. Key technologies involved in a runtime rendering of a Heritage Coach Technology XML XSLT HTML CSS JavaScript Description The design of a Heritage Coach is described in Extensible Markup Language (XML).How Heritage Coaches work Before you customize Heritage Coaches. in an HTML format. to the user in the Heritage Coach client. JavaScript that is embedded in the XML definition of a Heritage Coach is evaluated by the runtime engine before it is rendered to HTML by the web browser client. Coach_designer. The Extensible Stylesheet Language Transformation (XSLT) transforms the XML definition to the runtime HTML form.xls.css files. IBM® BPM automatically generates the XML definition of the Heritage Coach. such as dynamically adding rows to a table or governing the visibility of Heritage Coach controls. for example CoachDesigner. Edit the JavaScript files . Parent topic:Customizing Heritage Coaches Related information: Specifying a custom CSS for a heritage coach 762 .If you have the required technical expertise.Override and customize Cascading Style Sheets (CSS) . you can use the following methods to customize Heritage Coaches: .Edit the XSL transformation rules The following topics describe some of the customization options most commonly used for Heritage Coaches.Edit the XML definition . add the necessary files to your process application as managed assets. See Managing external files for more information. production. Using this method. you can simply drag the image from the library in the Designer to the design area of an open Heritage Coach. Parent topic:Customizing Heritage Coaches Related information: Example: creating a template Stock controls 763 . see the related information. your images are included when you install snapshots of process applications on servers in test. To add custom images to non-Heritage Coaches. When you need to add custom images. or other environments.Adding custom images to a Heritage Coach Heritage Coaches can include corporate branding and other graphic customizations. When you add an image as a managed file. You need to replace this text with the class name that you want. type your CSS override settings. 8.Overriding CSS styles for selected controls and fields You can override Cascading Style Sheet (CSS) styles to customize the appearance of a Heritage Coach. Click the Customization option in the properties. type a name in the Class Name text box. type your CSS override settings. About this task You can create a CSS override for either the label of a Heritage Coach control or for the control itself as described in the following procedure: Procedure 1. To override the CSS styles for the Heritage Coach control itself. Click the Add Class button. } 12. click to select the Heritage Coach control that you want to customize. go back to the Customization properties for the selected control and click the Create control override button. which is stored directly within the Heritage Coach and can be accessed as described in the following step. In the CSS text box. click the top-level section of the Heritage Coach (named IBM® Business Process Manager Coach by default) and then click the CSS option in the properties. the following CSS override changes the color of the label text to red and the typeface of the label text to bold: . class_name . Parent topic:Customizing Heritage Coaches Related information: Specifying a custom CSS for a heritage coach 764 .twLabel { } CSS class. In the design area. 4.twControl { font-style:italic.twLabel { color:red. 5. In the design area. 7. the following CSS override changes the typeface of the text in the control to italic: . class . class_name . For example. This creates a . For example. 6. Save the Heritage Coach and then run the service to test the CSS overrides. this field includes the name. In the design area. 10. To override the CSS styles for the label of the Heritage Coach control. 11. Open the service that contains the Heritage Coach that you want to work with and then click the Coaches tab. 2. Under Class Details. font-weight:bold. By default. class_name .twControl { } CSS class. class_name . click the top-level section of the Heritage Coach (named IBM BPM Coach by default) and then click the CSS option in the properties. In the CSS text box. This creates a . } 9. 3. click the Create label override button. 765 . The product loads a default CSS that is similar to the coach_designer. and then the coach CSS override. (You can click the New button and add a CSS file as described in Managing external files.Specifying a custom CSS for a Heritage Coach You can use your own Cascading Style Sheet (CSS) to customize an entire Heritage Coach. When you initially create a Heritage Coach. Add the CSS file that you want to use to your current project or to a referenced toolkit as described in Managing external files. click the Select button and choose the CSS file that you added in step 1. Administrators can change the Heritage Coach CSS setting for process applications and toolkits as described in Editing process application settings and Editing toolkit settings. About this task The following procedure describes how to specify a custom style sheet for a Heritage Coach. Procedure 1.css file from the application settings does not remove the default CSS. it uses the Heritage Coach CSS setting for the process application or toolkit in which the Heritage Coach resides. Save the Heritage Coach and then run the service to test the CSS overrides. In the design area. The default Heritage Coach CSS for process applications and toolkits is the coach_designer. 3. 2. You can add or override default style guidelines by using a custom CSS file in the coach or process application CSS override setting.) 5. process application or toolkit. Removing the coach_designer. click the top-level section of the Heritage Coach (named IBM® Business Process Manager Coach by default) and then click the Heritage Coach option in the properties. Open the service that contains the Heritage Coach that you want to work with and then click the Coaches tab. For the CSS Override field. 4. Note: More specific object matches for CSS style guidelines take precedence over less specific matches.css file that is stored in the System Data toolkit.css file from the system toolkit in the current version of the product. The coach CSS override takes precedence because the files are loaded in this order: product defaults. Parent topic:Customizing Heritage Coaches 766 . click the Select button and choose the . 4. For the XSL Transform Override field. Add the . Save the Heritage Coach and then run the service to test the XSL transform override. 5. Note: When you initially create a Heritage Coach. it uses the Heritage Coach XSL setting for the process application or toolkit in which the Heritage Coach resides. Open the service that contains the Heritage Coach that you want to work with and then click the Coaches tab. About this task The following procedure describes how to specify a custom XSL transform for a Heritage Coach.xsl file to customize an entire Heritage Coach. You can click the New button and add a new .xsl file as described in Managing external files. In the design area. Parent topic:Customizing Heritage Coaches 767 . The default Heritage Coach XSL for process applications and toolkits is the CoachDesigner.xsl file that is stored in the System Data toolkit. Administrators can change the Heritage Coach XSL setting for process applications and toolkits as described in Editing process application settings and Editing toolkit settings. Procedure 1. 3. click the top-level section of the Heritage Coach (named IBM® Business Process Manager Coach by default) and then click the Heritage Coach option in the properties.xsl file that you want to use to your current project or to a referenced toolkit as described in Managing external files. 2.xsl file that you added in step 1.Specifying an XSL transform override for a Heritage Coach You can use your own . twControl { } CSS class.twControl { width:110px. 6. 8. Open the service that contains the Heritage Coach that you want to work with and then click the Coaches tab. By default. 7. type a name in the Class Name text box. About this task Setting the maximum length for an Input Text control does not restrict the number of characters that a user can type into the text box. 4. Save the Heritage Coach and then run the service to test the CSS overrides. This creates a . Under Class Details. Parent topic:Customizing Heritage Coaches Related information: Making an input control a required field in a heritage coach 768 . Click the Customization option in the properties. For example. To override the CSS styles for the Heritage Coach control. the following CSS override sets the length to 110 pixels: . this field includes the name. In the design area. class . Click the Add Class button. class_name . } 9. 3. click the Create control override button. Procedure 1. 2. In the CSS text box. In the design area. click to select the Heritage Coach control that you want to customize. 5. type the CSS override settings to specify the maximum input length (in pixels) for the control's input text box.Setting the length of input text fields Overriding CSS styles in a Heritage Coach control also enables you to set the maximum length (in pixels) for an Input Text control. class_name . You need to replace this text with the class name that you want. click the top-level section of the Heritage Coach (named IBM BPM Coach by default) and then click the CSS option in the properties. click to select the Heritage Coach section that you want to customize. You need to replace this text with the key name that you want. 6. 7. About this task You can add a custom attribute to enable users to expand and collapse a section in a Heritage Coach as described in the following procedure: Procedure 1. In the design area. Save the Heritage Coach and then run the service to test the custom attribute. IBM® Business Process Manager provides the following attributes that you can use just as the showHide attribute is used in the preceding steps: Table 1. type true in the Value text box. When you switch to the Heritage Coach XML view. What to do next The custom attributes that you add when building a Heritage Coach pass information to the XSL about how the page should be rendered. Type showHide in the Name text box. 2. this field includes the name.Enhancing interface layout using custom attributes You can add custom attributes to Heritage Coach sections and controls to enhance the layout of the interfaces that you create for users. To make the section collapsible. By default. you can see any name-value attributes in the XML. Open the service that contains the Heritage Coach that you want to work with and then click the Coaches tab. Available custom attributes Attribute cssStyle cssClass Description Overrides a CSS style Overrides a CSS class (be sure to include the standard CSS class if you want the default functionality as well) Applies to Input Text (or equivalent) Input Text (or equivalent) 769 Example value width: 100px inputText important . 5. You need to replace this text with the value that you want. value . this field includes the text. type hidden in the Value text box. Note: To make the section collapsible and collapsed by default.Note: This example requires a Heritage Coach section with a visible title that is nested within another section. key . 3. 4. Click the Add Attribute button. By default. Click the Customization option in the properties. height width precision symbolPre symbolPost position Enables scrollable tables and sections (the table or section will always be the given height. such as on top (the label must be visible) Table or Section 200px Cell 75% InputText or Output 2 Text InputText $ InputText % Label top You can create completely new attributes and extend the capabilities of the Coach Designer by adding XML attributes directly to a Heritage Coach's XML. even when there is not enough data to fill it. When you add attributes to a Heritage Coach's XML.) Sets the width of a table column Displays numbers with the specified number of digits after the decimal Displays the given symbol before a value Displays the given symbol after a value Specifies the location of a label. you need to customize the Heritage Coach XSL to support the new attribute. Parent topic:Customizing Heritage Coaches Related information: Specifying an XSL transform override for a heritage coach 770 . The header of the table scrolls with the data. The System Data toolkit provides ready-to-use services for implementing and managing conditional activities. The primary service. This template for conditional activities is specific to a single process definition.System services to implement conditional activities The System Data toolkit includes services and a Heritage Coach that can serve as a template to implement and manage conditional activities. Parent topic:Building Heritage Coaches 771 . provides a sample Heritage Coach for selecting conditional activities at run time using a graphical interface. You can have multiple templates per one process definition. The System Data toolkit also includes a Heritage Coach to serve as a template for conditional activities named lsw Save Conditional Activity Template Coach. lsw Conditional Activity Selection Coach . A configured onClick event for a button does not take place at run time. submitting data in a section does not submit data in another section. If possible. Input values are not captured as expected at run time. If you experience problems running services that include Heritage Coaches. assign default values to them. Parent topic:Building Heritage Coaches Related information: Building heritage coaches 772 . Common Heritage Coach problems Issue Dynamic values are not displayed in a Heritage Coach as expected. design your Heritage Coaches such that you can distribute the rules across more than one Heritage Coach. Always design your Heritage Coaches with this rule in mind. the variable has no value versus the value 0). Another option is to use custom JavaScript to express cascading rules. Each section is its own HTML form. Ensure that the onClick event is assigned to the individual button instead of a Button Group control. This can happen when using multiple sections in a Heritage Coach. An example of nested visibility rules is described in Displaying a control based on the input value of another control in a heritage coach. Unexpected behavior of nested visibility rules at run time. An example is provided in Changing the visibility of a heritage coach control. unless it is a nested section.Troubleshooting Heritage Coaches Learn how to identify and fix common problems with Heritage Coaches. check for the issues described in the following table: Table 1. Potential cause and resolution You might be using null values in the variable (that is. When initializing variables in the service that contains the Heritage Coach. Localizing user interfaces You can provide localized interfaces for your users by replacing strings for labels and hover help with localization keys.Localizing coach view configuration options You can provide localized configuration options for your coach authors at design time by replacing strings for configuration option labels and hover help with localization keys. When the user runs the application. for example.Creating localization resources Localization resources for a process application are contained in localization resource bundles. In addition to providing translated versions of your applications for business users. the default text that is specified in the resource bundle is used. For each supported language there is a corresponding file containing translated values for all of the keys.Localizing process applications Localizing your process applications enables users in different language locales to interact with the application interfaces in their own languages. fully-localized design environment. users that are creating their own interfaces using custom coach views that you provide. . localizing your user-defined configuration options results in a more seamless. Parent topic:Creating user interfaces for business processes 773 . Otherwise. . which are a set of files that define key-value pairs for all the strings that are displayed in the application. Since the predefined configuration options are already set up for localization. you can also specify localized strings for your design-time users. the interface text appears in the language associated with their locale if the translated string is available. . zip file to select it and click Finish. which are a set of files that define key-value pairs for all the strings that are displayed in the application. 2. enter a translation key and a default value for that key. 8. or if you did not perform Step 4.Note: Language support also extends to specific countries. create a copy of the exported properties file. and so on). en_CA). en. Provide a name for your new resource bundle and click Finish. French (fr and fr_CA). and CC is the uppercase country code (CA. Optional: If you opened the Process Designer desktop editor. then for any given language. and so on). In the library. BR. After you have defined all of your translation keys. If you select to overwrite the values for all existing keys. 7. click the plus sign next to User Interface and select Localization Resource. Any new keys are added to the existing set of keys in the existing localization resource. For each translatable string in your application. key values in the imported files that do not match the existing key values will replace the existing values.properties where ll is the lowercase language code (fr. Browse to your updated . different locale options are provided for English (en_US. For each supported language there is a corresponding file containing translated values for all of the keys. 6.properties where ll is the lowercase language code (fr. renaming it according to the language that it will be supporting. Have each of the files translated into the corresponding languages. US. you can export the resource bundle for translation. and so on). 3. The default value is the value that is displayed if no translation is available. 10.zip file to which you will add the corresponding translated properties files. you can add each of the language locales that you will translate your user interface into by clicking Add and selecting each locale from the list.properties and you want your application to support Japanese. 774 . To import your resource bundle into your process application. you need to manually create a new properties file for each language locale that you will translate your user interface into. and Portuguese (pt and pt_BR). For each language that you want your application to support. and is as follows: my_application_ll. 4. or my_application_ll_CC. 9. For example. create a copy of the file called my_application_ja. Click Export to export the existing set of keys to a . en.Creating localization resources Localization resources for a process application are contained in localization resource bundles. 5.properties. pt. Open Process Designer and your process application or toolkit in the Designer view. pt. if your default properties file is my_application. For example. If you are in the web editor.The file naming scheme follows that of the Java specification. Procedure 1. open the localization resource file in Process Designer and click Import. the default value is displayed in any interfaces that reference this key. Click each of the languages that are flagged with a warning to see which key translations are missing. What to do next After you have created your localization resources.11. you can associate them with your coach views or human services by going to the Variables tab. warnings are displayed. If you do not supply translations for these keys. Parent topic:Localizing process applications 775 . If there are any missing keys in any of the translated files. Save your human service or coach view. 4. the default text that is specified in the resource bundle is used. and test your localizations by changing your language settings. See Creating localization resources. Click Assign a variable next to the Label field and select the localization key for the control label. and verifying that the localized strings appear in your interface. In the Coaches tab of the human service or the Layout tab of the coach view. Procedure 1. When the user runs the application. Click Assign a variable next to the Documentation field and select the localization key for the hover help text for this control. Before you begin Create or upload your localization resource file to provide the localization keys for your interfaces. the interface text appears in the language associated with their locale if the translated string is available. Parent topic:Localizing process applications 776 . click the plus sign next to Localization Resources and select the localization resource bundle that contains the strings for your interface. 3. Otherwise.Localizing user interfaces You can provide localized interfaces for your users by replacing strings for labels and hover help with localization keys. select the control that you want to localize. 5. Go to the Variables tab of the coach view or human service that contains your coach. 2. Localizing coach view configuration options You can provide localized configuration options for your coach authors at design time by replacing strings for configuration option labels and hover help with localization keys. and verifying that the localized strings appear with your configuration property. fully-localized design environment. select the configuration option that you want to localize. Since the predefined configuration options are already set up for localization. 6. Procedure 1. Parent topic:Localizing process applications 777 . 3. About this task There are two types of localization you can set up for your configuration options: the label text which identifies your configuration option in the coach view configuration properties. click the plus sign next to Localization Resources and select the localization resource bundle that contains the strings for your interface. 4. In the Variables tab for the coach view. If you are grouping a set of configuration options together under a group heading. Before you begin Create or upload your localization resource file to provide the localization keys for your configuration options. Click Assign a variable next to the Label field and select the localization key for the configuration option label. and the hover help text that helps your user understand how to set the configuration option. localizing your user-defined configuration options results in a more seamless. Click Assign a variable next to the Documentation field and select the localization key for the configuration option hover help text. 5. you can localize the group name by clicking Assign a variable next to the Group field and selecting the localization key for the configuration option group label. 2. See Creating localization resources. Save your coach view and test your localizations by reusing the coach view in a coach or coach view. In the Layout tab of the coach view. changing your language settings. either remove the original or leave it running.0 will have the acronym of 10. For process applications. For example. when you install a new snapshot. You can run different versions (snapshots) of a process application concurrently on a server. it is important to remember that a process application is a container that holds various artifacts used in or by the process application (for example. Versioning considerations for process applications in multiple clusters You can install the same version of a process application to multiple clusters within the same cell. create a snapshot for each installation and include a cell-unique ID in the snapshot name (for example. If the project manager decided that the additional changes to the service were not worthwhile. toolkit references. To understand how process applications are versioned.<minor>.3.0.3. and to be able to concurrently run multiple snapshots on a process server. the project manager can revert to the snapshot of the original fix. Each snapshot is a new version of the process application (from a 778 . The global namespace is specifically either the process application's tip or a particular process application snapshot. process models or BPDs.0. you cannot edit the snapshot acronym. a snapshot name of 1. The version name used by the server cannot be longer than seven characters. You can compare snapshots to determine differences between the versions. or monitor models). if a developer fixed a problem with a service and took a snapshot of its containing process application or toolkit at that point. so the assigned name is an acronym that uses characters from the snapshot name that you assigned. Snapshot acronyms areidentical to their snapshot names if the snapshot names conform to the recommended IBM VRM style and are not more that seven characters. See the topics about naming conventions for a more detailed description of this versioning scheme.0 will have an acronym of 1. The snapshot acronym will be guaranteed to be unique within the context of the process application within the scope of the Process Center server.0_cell1_1 and v1. For that reason. IBM® Business Process Manager assigns a global namespace for each process application.0. For example.Versioning process applications Versioning provides the ability for the runtime environment to identify snapshots in the lifecycle of a process application.0_cell1_2). Version context Each snapshot has unique metadata to identify the version (referred to as version context). not at the level of the individual artifacts. services.0. and then a different developer made several additional changes to the same service and took a new snapshot. and a snapshot name of 10. the project manager can compare the two snapshots to determine which changes were made when and by whom.<service>. v1. You assign that identifier. To differentiate among these multiple installations of the same version of the process application. tracks. but IBM recommends using a three-digit numeric version system in the format <major>. that means that versioning happens when you take a snapshot. Any versioning is done at this container level. and then the owners of process applications and toolkits can decide whether they want to move up to the new snapshot. Afterward. however. When you install a process application in a cluster. . but the content and function are the same.Naming conventions A naming convention is used to differentiate the various versions of a process application as it moves through the lifecycle of updating. Toolkit snapshots. undeploying.pure lifecycle management perspective). Parent topic:Building process applications Related information: Creating new process applications Managing snapshots Versioned modules and libraries 779 . if you want to update the toolkit. an automatic synchronization of the nodes is performed. co-deploying. and archiving. you must take another snapshot of "tip" when you are ready. Versioning considerations for Process Designer toolkits Remember that process application snapshots are typically taken when you are ready to test or install. deploying. are typically taken when you are ready for that toolkit to be used by process applications. The version context varies.22. undeploying.The track acronym is automatically generated from the first character of each word of the track name. . A business process definition in a process application is typically identified by the process application name acronym. A version context is a combination of acronyms that uniquely describes a process application or toolkit.<modification> scheme (for example.The snapshot acronym is created automatically when the snapshot is created.You might be unable to invoke a business process definition created in IBM Process Designer from a BPEL process created in IBM Integration Designer. It can be a maximum of seven characters in length.3 snapshot acronym. 1.If the snapshot name meets the criteria for a valid snapshot acronym. Note: When using the mediation flow component version-aware routing function. name your snapshot so that it conforms to the <version>.<release>. the digit values are limited to a maximum of five total digits (five digits plus two periods). depending on how the process application is deployed. which can also include a period. (A tip is the current working version of 780 . In addition.The process application acronym is created when the process application is created. For example. co-deploying.Naming conventions A naming convention is used to differentiate the various versions of a process application as it moves through the lifecycle of updating. When duplicate names exist.0. The acronym is limited to a maximum length of seven characters from the [A-Z0-9_] character set. . For example. except for the snapshot acronym. Therefore. It can be a maximum of seven characters in length. Each type of acronym has a naming convention.You might be unable to expose the business process definitions as web services without some form of mediation. you can deploy the tip of a process application or the tip of a toolkit. deploying. and the name of the business process definition. because anything beyond the first seven characters is truncated. you can deploy a snapshot of a process application as well as a snapshot of a toolkit. This section provides you with the conventions that are used to uniquely identify versions of a process application. . a new track created with the name My New Track would result in an acronym value of MNT.Naming conventions for Process Center server deployments On the IBM Process Center server. care should be taken when the digit fields are incremented. Because the snapshot acronym is limited to seven characters. a snapshot name 11.33 results in a 11. Choose unique names for your business process definitions whenever possible. the snapshot acronym.0). .The default track name and acronym are Main. . Deployment to a IBM® Process Center server includes the track acronym in the versioning context if the track acronym is not Main. the snapshot name and acronym will be the same. you might encounter the following problems: .22. and archiving. Parent topic:Versioning process applications 781 . you can deploy the snapshot of a process application.your process application or toolkit. depending on the type of deployment.Naming conventions for Process Server deployments On the Process Server. The process application snapshot acronym is used to uniquely identify the version.) The version context varies. . For process application tip deployments.Process application name acronym . (A tip is the current working version of your process application or toolkit. but the lifecycle of each toolkit is bound to the lifecycle of the process application. the version context is a combination of the following items: . In addition.Toolkit name acronym . Toolkits can be deployed with one or more process applications. see the Examples section. Each process application has its own copy of the dependent toolkit or toolkits deployed to the server. the version context is a combination of the following items: . For more information.Toolkit snapshot acronym Tips Process application tips are used during iterative testing in Process Designer. A deployed toolkit is not shared between process applications. depending on the type of deployment.Process application snapshot acronym Stand-alone toolkits For toolkit snapshot deployments. the version context is a combination of the following items: . later in this topic.Process application track acronym (if a track other than Main is used) .Process application track acronym (if a track other than Main is used) . you can deploy the tip of a process application or the tip of a toolkit. They can be deployed to Process Center servers only.Process application name acronym . For process applications. the version context is a combination of the following items: 782 . the track acronym is also part of the version context. Process application snapshots For process application snapshot deployments. They are not deployed to a production server. the process application tip or the specific process application snapshot is used to uniquely identify the version. you can deploy a snapshot of a process application as well as a snapshot of a toolkit.Naming conventions for Process Center server deployments On the IBM® Process Center server.) The version context varies.Toolkit track acronym (if a track other than Main is used) . For toolkit tip deployments."Tip" Toolkit tips are also used during iterative testing in Process Designer. If the track associated with the process application is named something other than the default of Main. The following table shows an example of names that are uniquely identified..Toolkit track acronym (if a track other than Main is used) . as shown in the following table:Table 2."Tip" Examples Resources should be uniquely named and identified externally using the version context.Toolkit name acronym .ear PA1-Tip-M2. SCA modules and version-aware EAR files SCA module name Version-aware name 783 Version-aware EAR/application name . . as shown in the following table:Table 4. a process application tip uses the default track name (Main):Table 1.ear . SCA modules and version-aware EAR files SCA module name Version-aware name M1 M2 PA1-Tip-M1 PA1-Tip-M2 Version-aware EAR/application name PA1-Tip-M1. Process application tip with default track name Type of name Process application name Process application name acronym Process application track Process application track acronym Process application snapshot Process application snapshot acronym Example Process Application 1 PA1 Main "" (when the track is Main) Tip Any SCA modules associated with this process application tip include the version context.The following table shows an example of a process application tip that uses a nondefault track name: Table 3. Process application tip with non-default track name Type of name Process application name Process application name acronym Process application track Process application track acronym Process application snapshot Process application snapshot acronym Example Process Application 1 PA1 Track1 T1 Tip Any SCA modules associated with this process application tip include the version context. In this example. ear . as shown in the following table:Table 6.The following table shows an example of names that are uniquely identified. SCA modules and version-aware EAR files SCA module name Version-aware name M1 M2 PA1-PSV1-M1 PA1-PSV1-M2 Version-aware EAR/application name PA1-PSV1-M1.ear PA1-PSV1-M2.ear Similar naming conventions apply to advanced Toolkit tip and snapshot deployments. They also apply to advanced snapshots installed to Process Server. Process application snapshot with non-default track name Type of name Process application name Process application name acronym Process application track Process application track acronym Process application snapshot Process application snapshot acronym Example Process Application 1 PA1 Track1 T1 Process Snapshot V1 PSV1 Any SCA modules associated with this process application snapshot include the version context. SCA modules and version-aware EAR files 784 . as shown in the following table:Table 8. .The following table shows an example of a process application snapshot that uses a non-default track name: Table 7.M1 M2 PA1-T1-Tip-M1 PA1-T1-Tip-M2 PA1-T1-Tip-M1. In this example. Process application snapshot with default track name Type of name Process application name Process application name acronym Process application track Process application track acronym Process application snapshot Process application snapshot acronym Example Process Application 1 PA1 Main "" (when the track is Main) Process Shapshot V1 PSV1 Any SCA modules associated with this process application snapshot include the version context. a process application snapshot uses the default track name (Main): Table 5.ear PA1-T1-Tip-M2. SCA module name Version-aware name M1 M2 PA1-T1-PSV1-M1 PA1-T1-PSV1-M2 Parent topic:Naming conventions 785 Version-aware EAR/application name PA1-T1-PSV1-M1.ear .ear PA1-T1-PSV1-M2. 0.0. For process application snapshot deployments. you can deploy the snapshot of a process application.jar Parent topic:Naming conventions 786 . such as a module or library.0-Lib2 PA1-1.0.0.0-Lib2.jar PA1-1.Process application snapshot acronym Resources should be uniquely named and identified externally using the version context.0-M2 Version-aware EAR/application name PA1-1.0.0.ear The following table shows an example of two process-application-scoped libraries and how the associated JAR files include the version context:Table 3.0-M2.0-M1. The following table shows an example of two modules and how the associated EAR files include the version context:Table 2.0 A resource.0.0-Lib1.ear PA1-1. The process application snapshot acronym is used to uniquely identify the version.0-Lib1 PA1-1. Example of names and acronyms Type of name Process application name Process application name acronym Process application snapshot Process application snapshot acronym Example Process Application 1 PA1 1. The following table shows an example of names that are uniquely identified: Table 1.0. SCA modules and version-aware EAR files SCA module name Version-aware name M1 M2 PA1-1.0-M1 PA1-1.0.Naming conventions for Process Server deployments On the Process Server. the version context is a combination of the following items: .0.Process application name acronym .0 1. Processapplication-scoped libraries and version-aware JAR files SCA process-applicationscoped library name Lib1 Lib2 Version-aware name Version-aware JAR name PA1-1. has the version context as part of its identify. 787 . Integrating with Enterprise Content Management (ECM) systems You can interact with an Enterprise Content Management server to store or view documents. There are. Parent topic:Building process applications 788 .Enabling document support . edit. you can create. you can use Enterprise Content Management (ECM) tools to work with IBM BPM documents in the embedded IBM BPM document store.Working with IBM BPM documents In IBM Business Process Manager. . special considerations for some of the CMIS operations that can be performed. however. and work with documents in the document store using either a Coach or a Heritage Coach. For example. The IBM BPM document store The IBM® BPM document store store is a CMIS-enabled embedded document repository that is used to store IBM BPM documents in IBM Business Process Manager version 8. edit. special considerations for some of the CMIS operations that can be performed. IBM BPM documents are represented by instances of the predefined document type IBM_BPM_Document. and work with documents in the document store using either a Coach or a Heritage Coach. . For example. There are.5. .Inbound events for the IBM BPM content store The IBM BPM content store supports a subset of the inbound content event types that are supported by external Enterprise Content Manager systems. .The IBM_BPM_Document document type In the IBM BPM document store. Event subscriptions for the IBM BPM content store can be created only by using the IBM_BPM_Document type. It supplants the document attachment feature that was used in earlier releases. . however. .Working with the IBM_BPM_Document_Properties property Working with documents through the Content Integration node usually requires the manipulation of document properties. . About this task The following topics provide additional information about working with IBM BPM documents: . The IBM BPM document store supports most Content Management Interoperability Services (CMIS) operations and a number of inbound events and you can use either Coaches or Heritage Coaches to work with IBM BPM documents in the document store. . you can create.Inbound events for the IBM BPM document store The IBM BPM document store supports a subset of the inbound content event types that are supported by external ECM systems.Creating IBM BPM documents You can create IBM BPM documents by using one of the documents Coach views and by using content integration in a service.0. The Document List will 789 . For IBM BPM documents (and unlike Enterprise Content Management documents).Updating IBM BPM documents You can update IBM BPM documents by using one of the documents Coach views and by using the Content Integration node in a service.Working with IBM BPM documents In IBM Business Process Manager. you can use Enterprise Content Management (ECM) tools to work with IBM BPM documents in the embedded IBM BPM document store. Event subscriptions for the IBM BPM document store can only be created using the IBM_BPM_Document type.Working with IBM BPM documents in the Document List coach view The Document List coach view can be configured to work with IBM BPM documents. the default search service included in the Content Management toolkit does not need to be overridden in the view configuration.0 or later. In most situations. Parent topic:Enabling document support 790 . you can successfully work around these limitations.build a CMIS query that is based on the specified IBM BPM document display options and then pass it to the service for execution. .Limitations in working with IBM BPM documents There are some limitations in working with IBM BPM documents. 0. The IBM BPM document store supports most Content Management Interoperability Services (CMIS) operations and a number of inbound events and you can use either Coaches or Heritage Coaches to work with IBM BPM documents in the document store.The IBM BPM document store The IBM® BPM document store store is a CMIS-enabled embedded document repository that is used to store IBM BPM documents in IBM Business Process Manager version 8. Parent topic:Working with IBM BPM documents 791 .5. It supplants the document attachment feature that was used in earlier releases.0 or later. Behavior will vary depending on the object and the action. An event produced when a user deletes a document. if a user deletes a document that has ten versions. For example. an event is fired for each item in the version series. When a document is deleted. Parent topic:Working with IBM BPM documents Related information: Performing modeling tasks for inbound events Adding a content event to a BPD Using intermediate and boundary message events to receive messages 792 . The inbound content event types that are supported for the IBM BPM document store are listed in the following table: Inbound content event types Checked In Associated object types Description Documents Checked Out Documents Check Out Canceled Documents Created Folders or documents Deleted Folders or documents Updated Folders or documents An event produced when a user checks in a document. An event produced when a user adds a document to the object store. An event produced on any action that updates the property values or content of a document. Event subscriptions for the IBM BPM document store can only be created using the IBM_BPM_Document type. ten events are fired.Inbound events for the IBM BPM document store The IBM BPM document store supports a subset of the inbound content event types that are supported by external ECM systems. An event produced when a user cancels the checkout of a document. An event produced when a user checks out a document. Note: An Updated event is fired each time a new document is created. 793 . An event that is produced when a folder has its file method called to file a Containable object. When a document or folder is deleted. an event is fired for each item in the version series.store Inbound events for the IBM BPM content The IBM® BPM content store supports a subset of the inbound content event types that are supported by external Enterprise Content Manager systems. if a user deletes a document that has 10 versions. An event that is produced when a user deletes a document or folder. An event that is produced when a user checks out a document. For example. An event that is produced when a user adds a document or folder to the object store. Case management functions are only available if you have IBM BPM Advanced with the Basic Case Management feature installed. An event that is produced when a user cancels the check out of a document. 794 . Event subscriptions for the IBM BPM content store can be created only by using the IBM_BPM_Document type. For example. The inbound content event types that are supported for the IBM BPM content store are listed in the following table: Inbound content event types Checked In Associated object types Description Documents Checked Out Documents Check Out Canceled Documents Class Changed Folders or documents Created Folders or documents Deleted Folders or documents Filed Folders An event that is produced when a user checks in a document. the user can change the class when the user checks in a document. 10 events are fired. An event that is produced when a user changes the class of the object. An event that is produced when a user changes the security of the object. Behavior varies depending on the object and the action. An event that is produced when a folder has its unfile method called to remove (unfile) a Containable object.Frozen Documents Locked Folders or documents Security Updated Folders or documents Unfiled Folders Unlocked Folders or documents Updated Folders or documents Version Demoted Documents Version Promoted Documents Parent topic:Working with IBM BPM documents 795 An event that is produced when an administrator or application freezes the custom properties of a specific document version. An event that is produced when a document version is promoted to a released version. An event that is produced when an item is locked for use by a custom application. An event that is produced when an item is unlocked for use by a custom application. An event that is produced on any action that updates the property values or content of a document or folder. Note: An Updated event is fired each time a new document or folder is created. . An event that is produced when a document version is demoted. Indicates whether Optional. original document or URL. overwritten. If a value instance identifier. process instance. IBM BPM documents are represented by instances of the predefined document type IBM_BPM_Document. The file name of the Optional. The numeric The identifier is document identifier automatically of the parent calculated and document in IBM cannot be BPM. The process Optional. If is not set. document is the document is associated to an associated to the instance (if the lifecycle of the document creation process instance. Value The identifier is automatically calculated and cannot be overwritten. the value content contains "FILE" is used. If a value the document is not set. If a value the document is not set. The properties for the document type IBM_BPM_Document are shown in the following table: Property Type IBM_BPM_Docume Integer nt_DocumentId IBM_BPM_Docume Integer nt_ParentDocument Id IBM_BPM_Docume String nt_FileType IBM_BPM_Docume String nt_FileNameURL IBM_BPM_Docume Boolean nt_HideInPortal IBM_BPM_Docume Integer nt_ProcessInstance Id Description The numeric document identifier in IBM Business Process Manager. "FILE" or references "URL". the should be hidden document is shown from Process in Process Portal. 796 . Indicates whether Optional. viewed by those The value can only users who have be set on document authority to view the creation. the this property is set.The IBM_BPM_Document document type In the IBM BPM document store. It is recommended that this property is set. Portal. is performed in the The document context of that content can only be process instance). IBM_BPM_Docume String[] nt_Properties IBM_BPM_Docume Integer nt_UserId The additional properties of the document. The caller can be the human service user (or the engine user when a human service is not used).) character. . the user ID of the caller is used. Parent topic:Working with IBM BPM documents 797 Optional. If a value is not set. The creator or last modifier of the document. The key and value should be separated by the comma (. Optional. see The IBM_BPM_Document document type. The object type ID and folder ID are automatically specified because they are mandatory properties when the IBM BPM document store is specified as the target server. see Working with the IBM_BPM_Document_Properties property. you can also provide content and properties: . The only required value for this operation is the document name. you select the IBM BPM document store as the target server and select the Create document operation. About this task You can use the following user interfaces to create IBM® BPM documents: .Creating IBM BPM documents You can create IBM BPM documents by using one of the documents Coach views and by using content integration in a service. . see Configuring coach views for storing and viewing Enterprise Content Management documents. For more information. see Working with document content.To provide content. Optionally. For information about constructing an ECMProperty list.To provide properties.The Content Integration node that is available in the human service. see Building a service that integrates with an ECM system or the IBM BPM document store. and integration service editors. Parent topic:Working with IBM BPM documents 798 . . For more information.One of the documents Coach views: Document List view (if it has been enabled to allow document creation) or the Documents view. For more information about default values. you can use an ECMContentStream variable. If you use the Content Integration node to create a document. Ajax service. All properties are optional and will default to a specific value if not specified. you can use a list of ECMProperty objects. For an example of how to create a content stream. . For sample code and information on working with content streams. you must first check out the document.Server: IBM BPM document store . see The IBM_BPM_Document document type. In the Content Integration node. In the Server Script node. see Building a service that integrates with an ECM system or the IBM BPM document store. In a service flow.One of the documents Coach views: Document List view (if it has been enabled to allow document creation) or the Documents view. and integration service editors. see Working with the IBM_BPM_Document_Properties property. specify the following options: .The Content Integration node that is available in the human service.Operation: Check-out document. a typical update procedure might involve the following tasks: Procedure 1. 3. When the content or properties data is ready to be updated. In the Content Integration node. specify the following options: . populate the implementation with the code that is required to update the content or properties. Parent topic:Working with IBM BPM documents 799 . see Configuring coach views for storing and viewing Enterprise Content Management documents. 2. The document ID (private working copy ID) that is returned by the check-out document operation must be used as input to the check-in document operation.Updating IBM BPM documents You can update IBM® BPM documents by using one of the documents Coach views and by using the Content Integration node in a service. For more information. To use the Content Integration node to update documents. the document must be checked in. Properties of an IBM BPM document can be updated only through a check-in operation. is not available for the IBM BPM document store.Operation: Check-in document. About this task You can use the following user interfaces to update IBM BPM documents: . Ajax service. The Update document properties operation. For more information. available for external Enterprise Content Management (ECM) servers. What to do next For sample code and information about working with IBM BPM document properties.Server: IBM BPM document store . About this task When you are working with IBM BPM documents. The IBM_BPM_Document_Properties property is defined as a string property that carries a name-value pair. only the intended updates are sent to the server." Information about working with the document property IBM_BPM_Document_Properties is found in the following topics: . IBM BPM document properties are stored in the single CMIS property object IBM_BPM_Document_Properties. then you must manually specify the format of the search condition. or configure the Content Integration node for a search operation.Specifying search criteria for the IBM_BPM_Document_Properties property After the "Document List" Coach View is configured to work with BPM documents.Updating the IBM_BPM_Document_Properties property In an update scenario. In both cases. each of which represents an extra property of the document. . This object contains the properties that are associated with the document. you can optionally provide the operation with a list of ECMProperty objects. The query includes any required search conditions from the IBM BPM document options that are specified for the view. . Be careful to ensure that when updating the property. you can use the document property IBM_BPM_Document_Properties to specify properties that are not defined in the document type IBM_BPM_Document. the existing value for the property is overwritten. When a value is passed to the property object.Reading from the IBM_BPM_Document_Properties property The get document operation returns an ECMDocument object. Information about the document type IBM_BPM_Document and all of its available properties is found in the topic "The IBM_BPM_Document document type. if you intend to write your own CMIS query. . Parent topic:Working with IBM BPM documents Related information: The IBM_BPM_Document document type 800 . it automatically generates the CMIS query to pass to the search service. However.Working with the IBM_BPM_Document_Properties property Working with documents through the Content Integration node usually requires the manipulation of document properties. only the properties that are passed into the check-in operation are updated in the document.Writing to the IBM_BPM_Document_Properties property Properties can be written into a document when it is created or updated. properties[0]. For an example of how to update the value of the IBM_BPM_Document_Properties property.ECMProperty().objectTypeId = "IBM_BPM_Document_Properties".listOf.object. In both cases.value[1] = "Property 2.value 2".Writing to the IBM_BPM_Document_Properties property Properties can be written into a document when it is created or updated.local.value[0] = "Property 1. tw. see the topic "Updating the IBM_BPM_Document_Properties property.value 1".value[2] = "Property 3. props. props.ECMProperty(). // Create the IBM_BPM_Document_Properties property entry tw.local. tw. // Initialize the properties input variable to be passed to the Content Integration node tw.object.object.object.ECMMultiValue(). The code below assumes that you want to overwrite the existing value of the IBM_BPM_Document_Properties property. About this task The following code shows an example of how to create the content of the IBM_BPM_Document_Properties property and store it into the list of ECMProperty objects that are passed into the document operation." Parent topic:Working with the IBM_BPM_Document_Properties property Related information: Updating the IBM_BPM_Document_Properties property 801 .local.properties[0]. you can optionally provide the operation with a list of ECMProperty objects. props.value 3". // Initialize the ECMMultiValue variable that will carry the name value pairs for the BPM properties var props = new tw. // Set the property name value pairs props.value = props.value.ANY().properties = new tw.local.properties[0] = new tw.listOf.value = new tw. Reading from the IBM_BPM_Document_Properties property The get document operation returns an ECMDocument object. // The BPM document properties object has been processed.bpmProperties[0] = new tw.bpmProperties[j]. This object contains the properties that are associated with the document.properties.listLength. } } 802 Exit the loop.local. j < bpmProperties. var nameValuePair = bpmProperties. there is an instance ECMMultiValue. } } break.properties[i].value". is .local.split(". tw.properties[i].object.object. Introspect this object and store everything into the // NameValuePair list.local. // Look for the BPM properties object for (var i = 0.listOf. tw.bpmProperties[j] = new tw.listLength.value[j]. tw.NameValuePair()."). }else{ // Else.document.bpmProperties = new tw. i < tw. Save its value to a local variable var bpmProperties = tw. if(typeof bpmProperties == 'string'){ // There is a string in the format "name.local. // If there was only a single name-value pair stored in the BPM properties. Need to check here.NameValuePair().name = nameValuePair[0].local.bpmProperties[0].name = nameValuePair[0]. tw.objectTypeId == "IBM_BPM_Document_Properties"){ // Found the BPM properties. Store it into the output variable.local. A list of NameValuePair objects used.NameValuePair().local.").document.local. tw. i++) { if(tw.value. j++) { var nameValuePair = bpmProperties.value = nameValuePair[1].bpmProperties[j]. About this task The following example code shows how to parse the value of the IBM_BPM_Document_Properties property into a variable that can be used in a service:// Initialize the variable that is used to store the BPM property values.value = nameValuePair[1]. tw.local.document.value. then // a string is returned.object.split(". for (var j = 0. tw.bpmProperties[0].local. Parent topic:Working with the IBM_BPM_Document_Properties property 803 . var bpmPropValues = bpmPropertiesEntry.ANY(). // This is made an instance of ECMMultiValue.value[0] = value.listLength. only the intended updates are sent to the server. j < tw. for (var j = 0. break.local.ECMMultiValue(). Assume that the tw.local.length. for example).value.Updating the IBM_BPM_Document_Properties property In an update scenario.value. which enables the update to be // handled generically even if the number of properties eventually changes. the existing value for the property is overwritten. bpmPropertiesEntry. the ECMProperty value will be a string.properties[j]. j++) { if(tw.value.bpmProperties.value = new tw.objectTypeId == "IBM_BPM_Document_Properties"){ bpmPropertiesEntry = tw.").document. Be careful to ensure that when updating the property.listOf. } // Cycle through the properties and update them with new values.bpmProperties[j]. if(typeof bpmPropertiesEntry.local. for (var i = 0. set the new value. i < bpmPropValues. for (var j = 0.name == nameValuePair[0]){ // Found the property. IBM BPM document properties are stored in the single CMIS property object IBM_BPM_Document_Properties.properties[j].document.value[i]. only the properties that are passed into the check-in operation are updated in the document. j++) { var updateValue = tw. j < tw. i++) { var nameValuePair = bpmPropValues.local. bpmPropertiesEntry.document // contains the document instance retrieved previously (by a get document operation.object.local. var found = false. 804 for the BPM .properties.value == 'string') { var value = bpmPropertiesEntry.object. bpmPropertiesEntry.local. var bpmPropertiesEntry.value. } } // If there is a single BPM document property. About this task The following example code shows how to update the value of the IBM_BPM_Document_Properties property object:// Find the ECMProperty object document properties.document.value = new tw.listLength. When a value is passed to the property object.value.split(". if(updateValue. value.value[bpmPropValues. } } // If the property is not found in the existing list.objectTypeId = "IBM_BPM_Document_Properties". } } // Now that the properties have been updated. tw.object.name + ".local.properties = new tw.properties[0] = new tw. // No need to add the property break.value = bpmPropValues.name + ".value. found = true.listOf.value.ECMProperty().properties[0].object.properties[0].value[i] = updateValue.bpmPropValues.local. // Property found.length] = updateValue. if(!found){ bpmPropValues. break out of the loop.local. Parent topic:Working with the IBM_BPM_Document_Properties property 805 . add it // to the set. tw.ECMProperty()." + updateValue.local. populate the update operation with the input tw.value." + updateValue. tw. To specify a search condition in the Content Filter page. About this task Whether you provide your own CMIS search query.To specify a search condition in the Content Filter page or to provide your own CMIS search query. if you intend to write your own CMIS query. the following search query will return the same results as the above search condition:ANY IBM_BPM_Document_Properties IN('approved.true') Additional information about specifying a CMIS query is found in the "Query" section of the OASIS Content Management Interoperability Standard (CMIS) specification. For the operator. or build it using the Content Filter page in the service editor. C. or configure the Content Integration node for a search operation. For example. Specify the search value in the format BPM_property_name. To provide your own CMIS search query. use the same format that is used for the search condition in the Content Filter page." 2. In the Search Criteria section. complete the steps in the following procedure: Procedure 1. However. complete the following steps: A. Additional information about specifying search criteria is found in the topic "Building a query for an Enterprise Content Management search operation. then you must manually specify the format of the search condition. The query includes any required search conditions from the IBM BPM document options that are specified for the view. the search condition approved. For example. Parent topic:Working with the IBM_BPM_Document_Properties property Related information: Building a query for an Enterprise Content Management search operation 806 .true would find all BPM documents that have a BPM property name approved with a value of true. it automatically generates the CMIS query to pass to the search service. B.search_value. select the Properties property. select the contains property. the search predicate needs to follow a specific format.Specifying search criteria for the IBM_BPM_Document_Properties property After the "Document List" Coach View is configured to work with BPM documents. you may also want to include the following properties to remain consistent with the default behavior: . MajorVersionNumber. The column shows the full name of the user. cmis:lastModificationDate. you must provide the user ID (rather than the full name of the user) in the WHERE clause of the CMIS select statement. IBM_BPM_Document_UserId.IBM_BPM_Document_FileType . IBM_BPM_Document_FileType. the default search service included in the Content Management toolkit does not need to be overridden in the view configuration. the Document List displays the Last Modified By column. which it obtains from the user ID value stored in the IBM_BPM_Document_UserId property.Your custom CMIS query must include the following document properties: . IBM_BPM_Document_FileNameURL. It is important to note that if you specify a query to filter for a specific user. The Document List will build a CMIS query that is based on the specified IBM BPM document display options and then pass it to the service for execution. cmis:objectId.MajorVersionNumber . About this task If you choose to provide your own search service and ignore the input CMIS query.cmis:objectId .cmis:name .cmis:versionSeriesId Optionally.IBM_BPM_Document_UserId The following example shows a sample CMIS query that includes all of these properties: SELECT cmis:name.IBM_BPM_Document_FileNameURL . the BPM document display options specified for the Document List will have no effect on the search result. Parent topic:Working with IBM BPM documents Related information: Document List control 807 .cmis:lastModificationDate . cmis:versionSeriesId FROM IBM_BPM_Document Note: If the IBM_BPM_Document_UserId property is specified. For IBM BPM documents (and unlike Enterprise Content Management documents).Working with IBM BPM documents in the Document List coach view The Document List coach view can be configured to work with IBM BPM documents. For more information." Parent topic:Working with IBM BPM documents Related information: Limitations in administering the IBM BPM document store Configuring the file size of uploaded content management documents 808 .xml configuration file to control the document file size.Limitations in working with IBM BPM documents There are some limitations in working with IBM BPM documents. In most situations. The IBM BPM document store restricts document size to 1 gigabyte or less If you attempt to create or enhance a BPM document and it results in a document size that exceeds 1 GB.The IBM BPM document store restricts document size to 1 GB (gigabyte) or less . you will receive an error message that directs you to reduce the document size. The IBM BPM document store is not available on all platforms Information about the platforms where the IBM BPM document store is not available is found in the topic "Limitations in administering the IBM BPM document store. As a system administrator. Some known limitations are: . you can use the document-attachment-max-filesize-upload option in the 100Custom. you can successfully work around these limitations. see Configuring the file size of uploaded content management documents.The IBM BPM document store is not available on all platforms These limitations are discussed in the following sections. you can create event subscriptions and design business processes and services that detect and respond to inbound content events from Enterprise Content Management (ECM) systems. or deletion of a document.Troubleshooting interactions with Enterprise Content Management systems From time to time. such as the creation. . you may encounter some issues during interactions with Enterprise Content Management (ECM) systems. and comply with industry and government regulations.Outbound interactions with Enterprise Content Management systems You can implement queries and services that interact with Enterprise Content Management servers. or end based on the type of content event. Adding the server to the Toolkit Settings Servers page allows the connection properties to be reused.Adding an Enterprise Content Management server You need at least one Enterprise Content Management (ECM) server for the service you develop. .Integrating with Enterprise Content Management (ECM) systems You can interact with an Enterprise Content Management server to store or view documents. In most situations. . You specify the connection properties to access an ECM server on the Process App Settings Servers page for a process application or on the Toolkit Settings Servers page for a toolkit. you can successfully work around these issues. You can access and update these documents from a business process by using Enterprise Content Management operations in services such as an integration service or human service. ECM systems are used to increase efficiency and to monitor the security of information. For Enterprise Content Management integration. images.Integration considerations for ECM products To work with specific ECM products. . it is helpful to have an understanding of their main integration considerations. Parent topic:Enabling document support 809 . The content events are used to catch and throw interactions with an ECM system. such as their CMIS capabilities and limitations. . modification. ECM systems manage documents of different types such as records. These types and services are contained in the Content Management (SYSCM) toolkit.Inbound events from Enterprise Content Management systems In IBM Business Process Manager. there are predefined types and services that you can use. continue. and web pages throughout their lifecycle. Business processes can instantiate. labwide. Beneath the Servers heading click Add. default values are used. About this task To add a server.com . . enter the following information. select Enterprise Content Management Server. You see the Process App Settings editor when you first click Open in Designer from a newly created process application in the Process Center. Enter the server location information (host name. .ibm. enter a meaningful name for server. For example: myHost. and password) for each environment type. These environments are described in the IBM Business Process Manager overview. You specify the connection properties to access an ECM server on the Process App Settings Servers page for a process application or on the Toolkit Settings Servers page for a toolkit. Select the Servers tab from the Process App Settings editor. Modifying the IBM Process Server environment type shows you how to change these types.Production: The environment where your services are deployed for use by your organization. If you do not provide values for these environments. . This field is optional. Alternatively you can select Process App Settings from the drop-down list on the toolbar in Process Designer. follow these steps. Adding the server to the Toolkit Settings Servers page allows the connection properties to be reused. port. . 810 . whether it is a secure server. . user ID. Procedure 1. context path.Staging: The environment where you deploy your services for pre-production testing. A connection must be established through Content Management Interoperability Services (CMIS) using the web services protocol rather than the Atom protocol. . From the drop-down list in the Type field.Adding an Enterprise Content Management server You need at least one Enterprise Content Management (ECM) server for the service you develop.Development: The environment where you develop your services.Environment Type: The environment of the Enterprise Content Management server. Beneath the Server Details heading. Beneath the Server Locations heading. . . repository name.Port: The port number of the Enterprise Content Management server.Default: If you do not provide values for the following environment types. 3.Test: The environment where you test your services. Specify an IP address or a host name and domain.Context Path: The path to the Content Management Interoperability Services (CMIS) web services application on the server. the values from the default environment type are used.Hostname: The host name of the Enterprise Content Management server. 2. Enter a meaningful description of the server in the Description field. From the menu.Password: The password of the user ID connecting to the Enterprise Content Management server.Always use this connection information: If selected.Secure server: Specify whether you want your service to be secure. which your service is associated with when a Document List or Document Viewer is configured. An administrator uses the Manage Users function to specify human service users. For example. You can change these settings at run time. . only this user ID and password are used for authentication.. select File > Save All. Parent topic:Integrating with Enterprise Content Management (ECM) systems Related information: Authentication scenarios Building a service that integrates with an ECM system or the IBM BPM document store 811 . . See Changing ECM server settings using the Process Admin Console. . .Repository: The name of your repository. If you select the HTTPS protocol. as described in Accessing an IBM Case Manager server using the Secure Sockets Layer (SSL). to use the Hypertext Transfer Protocol Secure (HTTPS) protocol by selecting this check box. 4. you must configure HTTPS security. Selecting this check box means this user ID and password overrides any other user information. 5. Click Test Connection to confirm the connection to the server works. that is. a human service.Userid: The user ID to connect to the Enterprise Content Management server. also has a user context. which is the default. Save your work. . Or.Working with a search result programmatically Search results can be substantial.Authentication scenarios IBM® Business Process Manager provides three ways that you can grant access to an Enterprise Content Management (ECM) server. . .How to use Coach views to store or view documents In client applications. you can design a business process that uses each method of authentication for different steps in the process. you can use the ECMContentStream data type to wrap a content stream and return information about the stream. You can design a business process to use personal credentials to control access to specific documents and folders on the ECM server. you may want to parse the search results programmatically. You can set a user ID and password for the process application that is recognized by the Enterprise Content Management system. Instead of working with a large search result in a user interface. .Working with document content To work with the content of documents.Building a service that integrates with an ECM system or the IBM BPM document store Use a service to allow a business process developed in IBM Process Designer to work with an Enterprise Content Management (ECM) system or the IBM BPM document store. . . A content stream is a stream of data that contains the content of a document.Outbound interactions with Enterprise Content Management systems You can implement queries and services that interact with Enterprise Content Management servers.Data mapping in Enterprise Content Management operations Each operation requires that variables be mapped to the input and output fields. you can store or view documents from an Enterprise Content Management (ECM) server by using functions that work with your search results. such as a word processing document or an image.Building a query for an Enterprise Content Management search operation A graphical interface helps you build a query to an Enterprise Content Management server. . Parent topic:Integrating with Enterprise Content Management (ECM) systems Related information: The IBM BPM document store The IBM BPM content store 812 . Using the auto-map function automatically creates and assigns variables of the right type to each field. At the end of the settings is a check box labeled Always use connection information specified here. Clear the Always use connection information specified here check box if you want to restrict which documents or folders individual users or specific user groups can see and use. When that check box is selected. the IBM BPM system uses individual user names and IDs for authentication and projects the identity to the 813 . Being authenticated on one system does not mean that a user or user group is also authenticated on the other system. When that check box is not selected. and allows fine-grained access control on the Enterprise Content Management server. In other scenarios. do not use this option if you want to restrict which documents or folders individual users can see and use. For example. you set a user ID and password (see the related links for more information about this task). Using this method. even if you set up single sign-on (SSO). The IBM Business Process Manager system and the Enterprise Content Management system are separate systems. the business process might generate public documents or perhaps all BPM users need to see the same collection of documents in a user interface. a static user name and password as defined in the process application settings is the only credential that can be submitted from IBM BPM to the Enterprise Content Management server. However.Authentication scenarios IBM® Business Process Manager provides three ways that you can grant access to an Enterprise Content Management (ECM) server. the ID and password do not need to be valid on the BPM system. there is no way of fine-grained access control and gathering auditing data by individual user. but they must be valid for the Enterprise Content Management server. Therefore. that user ID and password are attached to all calls made from that process application to the ECM server. If you use the default setting. This approach allows users to create and access private documents. You can set a user ID and password for the process application that is recognized by the Enterprise Content Management system. you want to project the user identity of the currently acting human user from the BPM system to the ECM system. The advantage of this method is that the Enterprise Content Management server is immediately available for use by the actions in the process application. In some scenarios. You can design a business process to use personal credentials to control access to specific documents and folders on the ECM server. If shared security is not configured. There is no way of telling the ECM system who the current "real" user is. provides records for audits. the IBM BPM system does not recognize Enterprise Content Management users and vice versa. the actual user identity of the human user who is working with IBM BPM does not matter in the Enterprise Content Management system. it might be enough to use a static system identity that represents the BPM system. Consider the way you want to share Enterprise Content Management information with IBM BPM users before you design your application. you can design a business process that uses each method of authentication for different steps in the process. Or. When you configure access to an Enterprise Content Management server in IBM Process Designer. which it is by default. In such cases. the user ID and password set on the process application are ignored.xml 814 . or by an integration service within a user task. A service that is started by a user task in a BPD runs under the security context of the user who claimed and started the task. In this latter case. the task owner identity is propagated to the ECM system.Enterprise Content Management server. If the Enterprise Content Management service is called by a system task in a BPD. authorization depends on how you model your business process. Parent topic:Outbound interactions with Enterprise Content Management systems Related information: Adding an Enterprise Content Management server Changing ECM server settings using the Process Admin Console The 99Local. by a coach. Calls that use the task owner identity fail if the BPM and ECM systems do not have shared security. you can restrict access to the Enterprise Content Management server to a user ID specified in the process application server settings or to a task owner. Now you can assign specific tasks to users who can see only the documents and folders that they need to complete those tasks. If the Always use connection information specified here check box is not selected. depending on the context. You can design a business process definition to use both authentication methods. If the Enterprise Content Management service is called by a human task. By choosing the context from which the call is made. the user that is identified in the process application settings is used.xml configuration files Changing IBM Process Server properties in 100Custom.xml and 100Custom. display a selected document.How to use Coach views to store or view documents In client applications. The ECM server that you are using determines the documents Coach view that you can use: . The following figure shows how business users work with documents on an ECM server through Coach views in the client application. you can configure your documents Coach view in one of the following ways: . The way that you configure the documents Coach view determines how the view behaves in your client application. To store a document. and store documents. by configuring one of the documents coach views 815 . users can retrieve a set of documents from an ECM server.Configure the documents Coach view that you are using with the Document Viewer view. You must also configure the Document Viewer view .External ECM server: Documents List view From these views. To view a document. use one of the documents Coach views in the user interface that you create for your client application.Configuring coach views for storing and viewing Enterprise Content Management documents You can store and view documents on an ECM server from a client application. you can store or view documents from an Enterprise Content Management (ECM) server by using functions that work with your search results. .Set a configuration option for the documents Coach view to display the document in a new window.IBM® BPM document store: Documents List view IBM BPM content store: Document Explorer view or Documents List view . such as Process Portal. (Document Explorer or Document List view) and. Parent topic:Outbound interactions with Enterprise Content Management systems 816 . optionally. a Document Viewer view. The parameter names in your search service must be the same as the names used in the Default ECM Search Service Ajax service: maxItems. see Building a query for an Enterprise Content Management search operation. Create a Human service. For the Document Explorer view.Configuring coach views for storing and viewing Enterprise Content Management documents You can store and view documents on an ECM server from a client application.Custom search service (Document List view only) .IBM® BPM document store IBM BPM content store .You must have an ECM service with a search operation that provides a search result.The search service that you create must comply with the interface of the Document List view. you can configure either the Document Explorer or the Document List view. All the following steps apply to both the Document Explorer view and the Document List. such as Process Portal. If you do not have a search service. a Document Viewer view. ensure that you also add the Dashboards toolkit to the dependencies. optionally. except when otherwise specified. . About this task Add one of the documents coach views to a coach to enable Process Portal users to store or view documents on an ECM server. 2. by configuring one of the documents coach views (Document Explorer or Document List view) and. you can configure the Document List view only. . Tip: Do not select the 817 . If you are using IBM BPM or an external ECM server. skipCount. ensure that the Content Management (SYSCM) toolkit is added to the dependencies for the process application. searchAllVersions. and cmisQuery.An external ECM server If you are using the IBM BPM content store. The What to do next section describes how to create a simple search service. The Default ECM Search Service Ajax service that is provided in the Content Management (SYSCM) toolkit shows an example of the expected input and output definition. you can create one when you configure the Document List view. Before you begin The Enterprise Content Management (ECM) server where the documents are stored can be any of the following: .Because you need access to ECM types. For information on how to create the ECM service. This search result is used to present a list of documents in the Document List view. Enter an appropriate name for the coach and save your work.Toolkit dependencies . Select a Coach from the palette and drag it onto the canvas. Procedure 1. cmisQueryString + ".photoSubject) tw.cmisQueryString + ". if (tw.cmisQueryString = tw. Document List view only. PhotoLocation". and save your work. B.cmisQueryString + ". Beside Binding.local. Beside Binding. Select the coach view and in the Properties section.local. 1. tw. 5.photoDate) tw. and from the Business Objects list. PhotoCatagory". and save your work. B. see Document Explorer control and Document List control. If you run a script to update the binding. 1. In addition.local.local. On the General tab in the Properties view. A. Tip: If you do not see a Content section on the palette. Select the documents coach view on the canvas. Beside Variable Type. select that section from the Filter list. cmis:objectId ". click Configuration. Beside the Search property. Select the documents coach view on the canvas.cmisQueryString = tw. click Select > documentInfo (ECMDocumentInfo) (List) > listSelected (ECMDocumentInfo). In the following JavaScript example. the columns are updated by appending text that changes the older values. because the values for the inputs to your search service changed. you must set its data binding property to communicate with your documents coach view.local. Select the other configuration options that you want for your implementation of the documents coach view that you are using to list documents.local.cmisQueryString = tw. if (tw. PhotoSubject". select the ECM service that implements the search operation. 3.local. if (tw. Test the implementation of the documents coach view by clicking the Run service icon in the upper right section of the page. C. click Add Private. click Select. drag one of the documents coach views onto the canvas. What to do next You might want to update bindings in the documents coach view by using a script. drag a Document Viewer view onto the canvas. Select Is List. In the Document List view. if you are using the Document Viewer view. On the Coaches tab. 2. If you also want to view documents in the coach. select ECMDocumentInfo. Open the new coach and from the palette beneath Content. 2. Create the data binding property. documentInfo. and save your work. On the Coaches tab.Heritage Coach. 4. and give the variable a name. if (tw. 3.local. On the Variables tab. click Select > documentInfo (ECMDocumentInfo) (List). which is used primarily with process applications.local. Set the data binding for the Document Viewer view.photoLocation) tw. A.cmisQueryString + ". you must change the previous value. for example. For more information about the configuration properties.local. 1.cmisQueryString = tw. for example. 6.local.local. Create and set the data binding property for the documents coach view if you are using the Document Viewer view to display a document in the list. 2. PhotoDate". On the General tab in the Properties view. 7. configure the search service that targets your ECM server.photoCatagory) tw. click Select. 818 .cmisQueryString = "SELECT cmis:name. Set the data binding for the documents coach View. From the menu beneath Ajax Service.local. If you configured the Document List view for an external ECM server.local. for example. MySearch. Rename the Default ECM Search Service to an appropriate name. To ensure that you have the correct input and output variables and types. Parent topic:How to use Coach views to store or view documents Related information: Building a service that integrates with an ECM system or the IBM BPM document store Specifying search criteria for the IBM_BPM_Document_Properties property Building a query for an Enterprise Content Management search operation Controls in the Content Management toolkit 819 . tw. Use the auto-map function to create the map between the input and output service parameters and the variables.cmisQueryString = tw.local. copy the Default ECM Search Service to your process application.testCoachRefresh + "XYZ ". then add a Content Integration step to the ECM documents path and configure the search operation with an Enterprise Content Management server. configure the search operation that is defined in the existing IBM BPM documents Content Integration step.tw.local.testCoachRefresh = tw. . 2.cmisQueryString + " FROM acpPhoto".local.If you configured the Document List view for the IBM BPM document store. 1. 3. 4. Complete one of the following steps: . The following steps show how to create a search service for the Document List view. the Server name input map is enabled and editable. follow these steps: Procedure 1. select + beside TOOLKITS. you can select one of the following server types in the Server field. To add this toolkit dependency. select Integration Service . .Select User Interface and then +. select the Content Management toolkit version you require.Building a service that integrates with an ECM system or the IBM BPM document store Use a service to allow a business process developed in IBM® Process Designer to work with an Enterprise Content Management (ECM) system or the IBM BPM document store. . 2.The name of an ECM server Information about the IBM BPM document store is found in the topic "The IBM BPM document store." If you want to select the name of an ECM server but no ECM servers are available for selection. The editor opens with the Diagram view in focus. if it has not been added as you will need access to the ECM types. You should add the Content Management (SYSCM) toolkit to your dependencies. The following services contain a Content Integration step. Under Enterprise Content Management Server. you should have added your Enterprise Content Management (ECM) servers to your process application as shown in Adding an Enterprise Content Management server. From the menu. drag a Content Integration step to the canvas and provide a meaningful name for it.Select User Interface and then +. From the menu. Click Implementation in the Properties view.IBM BPM document store . select Human Service. 3. About this task To build a service that integrates with an ECM system or the IBM BPM document store. select Ajax Service. It means that in the Data Mapping tab section. Enter a name for the service on the following dialog box and click Finish. you can add a server in the Process App Settings editor by 820 . From the menu. From the palette. In the Add dependency menu.Alternatively.Select Implementation in the library section and then +. Before you begin If you are working with an ECM system rather than the IBM BPM document store. Select any service from the library area that supports Content Integration steps. . You can pass a server name by using a variable in that field. <Use data mapping> is the default selection in the Server field. Check-out Checks out a document document. click Save and then switch to the service editor canvas again and select the server from the Server field. Information about adding an ECM server is found in the topic "Adding an Enterprise Content Management server. which makes it possible for other users to work with it. Create folder Creates a folder. select an appropriate ECM operation.selecting the Use the Process Application Settings editor to add a server link and then clicking the Servers tab. Delete document Deletes a document. Operation name Add document to folder Cancel check-out document Description Adds a document to a folder. giving all users access to it. Get all document Gets all versions of versions a document. only the person who checked it out can use it. Create document Creates a document. Under Content Operation. Get document Gets a document that matches a document identifier. Copy document Copies a document. Check-in document Checks in a document. The following table displays the name of each ECM operation and indicates whether the operation is available for external ECM systems and the IBM BPM document store. Available for external ECM systems? Yes Available for the IBM BPM document store? No Yes Yes Yes Yes Yes Yes Yes No Yes Yes Yes Yes No Yes Yes Yes No Yes Yes Yes Yes Yes 821 ." 4. Delete folder Deletes a folder. Releases a document from the check-out state. After adding the server. Get document Gets a stream of content data that is the content of the document. Remove document Removes a from folder document from a folder. Get type definition Gets the type definition of a document or folder (including its properties). You can create them manually by yourself or use the auto-map function. Search Retrieves a set of document or folder references according to a query. Update document Updates the properties properties of a document.Get documents in folder Get folder Gets all documents in a folder. which are used by the service you create. Get folder by path Gets a folder as determined by a path to it. Gets a folder that matches a folder identifier. These variables need to be created. Move folder Moves a folder. Get folder tree Gets a set of folders in an array. Click Data Mapping. 822 . Move document Moves a document from one folder to another. Yes No Yes No Yes No Yes No Yes Yes Yes Yes Yes No Yes Yes No No Yes Yes Yes Yes Yes Yes 5. In this section you can create the map between the variables for input and output. Click the auto-map icon to create these private variables." Set document Updates a content document with content. Get type Gets the type descendants definition descendants as determined by the depth level. The auto-map function creates private variables for the business objects. See "Building a query for an Enterprise Content Management search operation. 6. Parent topic:Outbound interactions with Enterprise Content Management systems Related information: Adding an Enterprise Content Management server Building a query for an Enterprise Content Management search operation How to use coach views to store or view documents Configuring coach views for storing and viewing Enterprise Content Management documents The IBM BPM document store 823 . if you have errors at run time. A content integration step may raise an error with error code ECMError and error data of type ECMError. See Handling errors in services. use catching error events to handle errors thrown by a content integration step.The mapping structure for each operation is discussed in Data mapping in Enterprise Content Management operations. What to do next As with any service. Save your work to update the process application with any changes to your service. Folder: A type of folder that contains documents. second.Building a query for an Enterprise Content Management search operation A graphical interface helps you build a query to an Enterprise Content Management server. the server could have a security type of folder for containing documents related to security.Under Object Type.Data Mapping: Select if you are experienced in writing Content Management Interoperability Services (CMIS) queries and want to write your own handcoded query (see the query section of the CMIS specification for information on the syntax). The layout of the result set. . Click Select and choose the folder type from those available on the server. As you select a property. select one of the following: . Beneath Build Search Filters complete the fields appropriate to your query. Columns are added from left to right. In the left column. if you created more than one search step. and the priority of which column is sorted first. . click Add to see a list of properties for the type you selected previously.Document: A type of document. . it appears as a column in the pane beneath Properties along with sample data from the selected Enterprise Content Management server.Selection will disable the fields in the Content Filters page and make the CMIS query Input Mapping field editable on the Data Mapping tab. Select additional properties based on your application. For example. For example.Under Properties. . Examine your application to decide what document type to select. select the search node you want to create your query for. third and so on is described in the following table. . an application about insurance claims might select insurance forms. . Click Select and choose the document type from those available on the server. click the Content Filters tab. the sorting of items in columns. 3. Procedure 1. 2. About this task Follow these steps to add a query that can be used in a search operation. the server could have an email type of document for storing critical information sent by email. 824 .Content Filters: (Default) Select if you want to use the fields on this Content Filters page to define your search.In the Method of creating search field. After specifying a search operation in an Enterprise Content Management service and selecting a server name. For example. you might want to add the property of when the insurance claim was made. These types are also discussed in the input and output fields described in Data mapping in Enterprise Content Management operations. select the type of object for the search. Using the application about insurance claims mentioned previously. you might want to only search for objects whose Current State is equal to Working. Save your work. 4. for removal. How to change the order Select a column and use the arrows at the bottom of the pane to move the column to the left or right.Under Search Criteria. Click X to remove a column from the sorting priority. Click the triangle at the top of a column which column is sorted first. Use the Add or Remove buttons to add or remove property columns. The IDs provide the links to each document in the content repository. What to do next Using Document List and Document Viewer views. column. Ascending or descending order of Click the number at the top of a items in each column. An 825 . select and view. The content of this variable is a CMIS query following the standard CMIS syntax (see the link to the CMIS standard page in the Data Mapping description). All returns items matching all the criteria specified in the filter. Select the arrows at the side of the pane to move a selection up or down in the priority list. The match criteria does not affect the search result columns shown in the Properties table though it will affect the rows. Alternately. For example. Match criteria lets you select all or any as a match criteria. File > Save All. Depending on the direction of the triangle. The sorting priority of the result set can alternately be done by selecting Result set order specified by process variable and mapping to a variable containing the sorting priority. you can turn your search into a list of documents that a user can browse. This option is helpful for having the sorting priority set at run time. the ID column should not be removed from the query. The third and so on. that is. However. Any returns items matching any single field in the filter. You may also use JavaScript. you can specify constraints for specific properties by selecting Add Search Criterion. Sorting priority of the result set. second. . the items will be arranged in an ascending or descending order. the ID column is not shown in the Document List. Layout and sorting sequence of the result set Layout and items sorted Layout of columns from left to right. If the column does not have a number at the top. If the Search operation is used with a Document List view.Table 1. select the triangle at the top of the column and from the menu select Remove property. click the triangle and select Add sort order. columns with a number open in a dialog box. and select Change sort order. including showing the document in a Document Viewer. Parent topic:Outbound interactions with Enterprise Content Management systems Related information: Building a service that integrates with an ECM system or the IBM BPM document store How to use coach views to store or view documents Configuring coach views for storing and viewing Enterprise Content Management documents 826 .ID is required to perform any actions on the document. searchResult. parsing a standard query returning a set of documents in business objects and parsing a strongly typed search result where the business object type is specified. /* * Check if a search result found. Instead of working with a large search result in a user interface. i < columnMetadata. } 827 .local. that is. and store them in an array. we take a generic search result and extract the IDs of all the documents found. /* Property metadata is captured by the ECMPropertyMetadata business object */ var columnMetadata = tw. Find which column contains the ID column and * save its index so we can retrieve the right value from each row. cmis:creationDate. . i++) { if (columnMetadata[i].searchResult.local. cmis:objectId FROM cmis:document ORDER BY cmis:name ASC. A strongly typed search result adds precision that can improve the performance when parsing it over the generic search result. break. In this example. The ECMSearchResult. When there is no return type specified for the search operation. which in turn holds a list of ECMSearchResultRow objects. you may want to parse the search results programmatically. In other words the query did not make use of the optional Return type input parameter where a specific business object type is specified. and can be used to search for specific columns.Parsing a strongly typed search result Parsing a generic search result The following JavaScript code assumes that query for the search result was created in the standard way as described in Building a query for an Enterprise Content Management search operation.propertyMetadata has the column information as specified in the CMIS query. Parsing search results programmatically can be subdivided into two methods: parsing a generic search result. as shown below. var idColumnIndex = -1.length. The Return type input parameter is described in the Search operation section in Data mapping in Enterprise Content Management operations. the ECMSearchResult.resultSet field contains an ECMSearchResultSet object.propertyMetadata. The SELECT statement used in the following example is SELECT cmis:name. Document IDs are a basic piece of information used by most of the ECM operations. */ if (tw.Working with a search result programmatically Search results can be substantial.numItems > 0) { for (var i = 0.queryName == 'cmis:objectId') { idColumnIndex = i.Parsing a generic search result . var resultSet = tw.local.} tw. The SELECT statement used in the following sample is SELECT cmis:objectId AS documentId FROM cmis:document .listOf. */ /* Set the return list of ECMSearchResultBO to output the output variable and we are done */ var resultSet = tw. i++) { tw.documentIds[i] = resultSet.length > 0){ tw.local.searchResult.local.documentBO = resultSet.row. The Return type input parameter is described in the Search operation section in Data mapping in Enterprise Content Management operations.row. we take a strongly typed result and extract the business objects returned by the search operation. The field for the Return type input parameter is only editable if you selected the Data Mapping option on the Content Filters page.ECMID().local. } } else { /* No search result */ } Parsing a strongly typed search result The following JavaScript code assumes that the query for the search result was created with the optional Return type input parameter where a business object type is specified.searchResult.resultSet. documentBO.local.documentIds = new tw.object. it is not provided for you. if(resultSet. /* In this example. } Parent topic:Outbound interactions with Enterprise Content Management systems Related information: 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 828 .column[idColumnIndex]. for (var i = 0. The Return type parameter should be mapped to a public output variable. for example. Note that you create the ECMSearchResultBO.resultSet.row. The ID column is mapped to the business object's documentID property in the CMIS SELECT statement.row[i]. Select the List check box. So we simply return the array of business objects for the caller to process.length. that has an ECMSearchResultBO type. i < resultSet. such as a word processing document or an image.Working with document content To work with the content of documents. The value of the document.lang.Check in document .Create document . The file name of the content stream. If the property is set. If the length is unknown. the MIME media type should match the value of the property cmis:contentStreamMimeType.org. application/pdf. The MIME media type of the content stream.getBytes("UTF-8"). ECMContentStream properties Property name contentLength mimeType fileName content Description The length of the original (nonencoded) content length in bytes. For the primary content of a document. the file name should match the value of the property cmis:contentStreamFileName. the length must be a positive number. For the primary content of a document. the property must not be set.Base64.String(value).java. you can use the ECMContentStream data type to wrap a content stream and return information about the stream.codec.binary. 829 .Set document content Information about these operations is found in the topic Data mapping in Enterprise Content Management operations.Get document content . The ECMContentStream data type is used in the following four Enterprise Content Management (ECM) operations: . A content stream is a stream of data that contains the content of a document. var bytesValue = new Packages. For example. var content64 = Packages. It must be of type String Base64 and encoded in UTF-8.commons. The properties for the ECMContentStream data type are described in the following table: Table 1.encodeBase64(bytesValue).apache. The following example code fragments can be used in a script activity to get and set values:// Script sample code to set and encode the document content var value = "abc". org. // Script sample code to get and decode the document content var byteValue = Packages.content = new Packages.object.local.contentStream.String(content64.local.String(content64. tw. tw.String(tw.mimeType = "text/plain". tw.contentStream.ECMContentStream(). "UTF-8").contentStream. Parent topic:Outbound interactions with Enterprise Content Management systems 830 .lang.java.contentLength = value.length.Base64.commons. "UTF-8").contentStream.getBytes(). var content64 = Packages.lang. var value = new java.tw.lang.content).codec.decodeBase64(byteValue).java.binary.local.local.local.apache.contentStream = new tw. This topic describes the ECM operations and the input and output fields of each operation as specified in the Data Mapping tab of the Properties view. IBM® BPM content store. The following table displays the hyperlinked name of each ECM operation and indicates whether the operation is available for external ECM systems. Operation name Add document to folder Cancel check-out document Check-in document Check-out document Copy document Create document Create folder Delete document Delete folder Get all document versions Get document Get document content Get documents in folder Get folder Get folder by path Get folder tree Get type definition Get type descendants Move document Move folder Remove document from folder Search Available for external ECM systems and IBM BPM content store? Yes Available for the IBM BPM document store? Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes No Yes No Yes No Yes Yes Yes Yes Yes Yes No Yes Yes Yes Yes Yes No No No Yes Yes Yes Yes Yes No No No Yes Yes 831 No .Data mapping in Enterprise Content Management operations Each operation requires that variables be mapped to the input and output fields. Using the auto-map function automatically creates and assigns variables of the right type to each field. and the IBM BPM document store. Output: .Server name (String): The name of the server containing the document. Cancel check-out document Input: .No output is returned. .Parent folder ID (ECMID): An identifier of the folder that will contain the document. you cannot pass the content stream parameter with the Check-in document operation. Output: . You can consult your ECM system documentation to determine whether a parameter is optional or mandatory for your ECM system.Server name (String): The name of the server containing the original document. Check-in document Input: .Note: If you have made updates to a document and your ECM system is Microsoft SharePoint. Information about the ECMContentStream data type is found in the topic Working with document content.Set document content Update document properties Update folder properties Yes Yes Yes Yes Yes No These operations are described in the following sections. If set to true then the document is a major version. . . However. which is the default. parameters that are marked as optional may actually be mandatory for some ECM systems.Document ID (ECMID): A unique identifier of a document object. Add document to folder Input: . the Content Management Interoperability Services (CMIS) specification is used to determine which operation parameters are marked as optional. .Major (Boolean): (Optional) An indicator of the version of the checked-in document. Note: In Process Designer.No output is returned. You must first pass the content stream parameter with the Set document content operation and then 832 . . such as Microsoft SharePoint.Private working copy document ID (ECMID): A unique identifier for the private working copy of the document object.Content stream (ECMContentStream): (Optional) A stream of data containing the content of the document such as a word processing document or an image.Private working copy document ID (ECMID): A unique identifier for the private working copy of the document object. Server name (String): The name of the server to contain the original document.Versioning state (String): (Optional) A name that defines the version of the document. .Document ID (ECMID): A unique identifier of the new document.A new name for the copied document. Output: .Document ID (ECMID): A unique identifier of the document object.Document ID (ECMID): A unique identifier of a document object.Server name (String): The name of the server containing the document.minor: The copied document is a minor version.checkedout: The copied document has a checked-out state. . Copy document Input: . . Valid values are: . .none: The copied document cannot be versioned.Object type ID (ECMID): This identifier corresponds to a class name defined on the ECM system that is used to create a document.you can use the Check-in document operation. . . . the value 833 . the major value is not a valid versioning state and you must use the none value instead.Check-in comment (String): (Optional) A comment about the checked-in document. If versioning is disabled. .Properties (ECMProperty []): (Optional) A set of named properties that can be in any order.Parent folder ID (ECMID): A unique identifier of the parent folder for the document.Document ID (ECMID): A unique identifier of a document. . .Properties (ECMProperty []): (Optional) A set of named properties that can be in any order.Private working copy document ID (ECMID): A unique identifier for a private working copy of the document object. . Output: . For example. When the name is set. Check-out document Input: . .major: (Default) The copied document is a major version.Name (String): Optional . Create document Input: . it overrides the name in the ECMProperty list (if specified). Output: .Server name (String): The name of the server for the document. a unique identifier for the new document is generated by the system and assigned to the variable. .Properties (ECMProperty []): (Optional) A set of named properties that can be in any order. if an output variable named outputDocumentId is defined.Folder ID (ECMID): A unique identifier of the new folder. Alternatively. After the Create document operation is successfully run. If versioning is disabled.outputDocumentId.Name (String): The name of the folder. . . .checkedout: The created document has a checked-out state. /MyFolder. It's base type must be a folder.local. . .none: The created document cannot be versioned. Output: . .major: (Default) The created document is a major version.Server name (String): The name of the server for the folder. a class name can be used that corresponds to a class derived from cmis:document.cmis:document can be used to define a basic document.Object type ID (ECMID): The ID of the object's type. . . the major value is not a valid versioning state and you must use the none value instead.Content stream (ECMContentStream): (Optional) A stream of data containing the content of the document such as a word processing document or an image. . a relative folder name for the root can be specified. Valid values are: . .Parent folder ID (ECMID): The identifier of the parent folder. for example. Information about the ECMContentStream data type is found in the topic Working with document content. 834 .Server name (String): The name of the server for the document. A right slash character (/) specified as the value denotes the root folder in the target server. Create folder Input: . . the IBM_BPM_Document object type ID is automatically specified and it cannot be changed.Properties (ECMProperty []): (Optional) A set of named properties that can be in any order. Alternatively.minor: The created document is a minor version. If you select IBM BPM document store as the server name. For example. .Name (String): The name of the document.Folder ID (ECMID): An identifier for the parent folder of the document. the selector button of the field can be used to set the value to tw. Output: .Versioning state (String): (Optional) A name that defines the version of the document.Document ID (ECMID): The value of this field identifies a variable that will be used by the service to store a unique identifier for the new document. Server name (String): The name of the server containing the document. The default is true.Server name (String): The name of the server containing the document.No output is returned. Output: . Output: .No output is returned.Content stream (ECMContentStream): The stream of data containing the content of the document.Delete document Input: .Document ID (ECMID): A unique identifier of the document. Output: .Server name (String): The name of the server containing the document. .Server name (String): The name of the server containing the folder.Documents (ECMDocument []): All versions of the document. . .Server name (String): The name of the server containing the document. Information about the ECMContentStream data type is found in the topic Working with document content. Output: . 835 . Get document content Input: . Get document Input: . .Document (ECMDocument): The document object.Version series ID (ECMID): The version series identifier that is stored in the cmis:versionSeriesId property. Get all document versions Input: . . Delete folder Input: . Output: .Folder ID (ECMID): A unique identifier of a folder object.Document ID (ECMID): A unique identifier of a document.Document ID (ECMID): A unique identifier of a document object. .All versions (Boolean): (Optional) States whether all versions of the document are to be deleted. Folder ID (ECMID): A unique identifier of a folder. . .Server name (String): The name of the server containing the folder.Server name (String): The name of the server containing the folder.Get documents in folder Input: . .Server name (String): The name of the server containing the folder. Get folder Input: .Folders (ECMFolder []): The folder objects contained within the specified folder and its level of descendants. It indicates the top level of the tree structure. Output: . Get type definition Input: . The default. 1. returns all descendant folders.Server name (String): The name of the server containing the object type. .Folder (ECMFolder): The folder object.Folder (ECMFolder): The folder object. Output: 836 . Output: . Get folder tree Input: .Server name (String): The name of the server containing the folder.Folder ID (ECMID): A unique identifier of a folder. A "/" represents a root folder.Path (String): The path to the folder. Output: . .Depth (Integer): (Optional) The number of levels of folders to return. Output: . Get folder by path Input: . .Object type ID (ECMID): The ID of an Object-Type.Documents (ECMDocument []): The documents contained in the folder.Folder ID (ECMID): A unique identifier of the folder containing the documents. Depth (Integer): (Optional) The number of levels of the type hierarchy to return. Output: . If not specified. Output: . .Object type ID (ECMID): (Optional) An ID of an Object-Type. The ECMObjectTypeDefinition object contains the type metadata.Object type definition (ECMObjectTypeDefinition): The definition of the type.Folder ID (ECMID): The identifier of the document.Source folder ID (ECMID): The identifier of the old parent folder. The default.Target folder ID (ECMID): A unique identifier of the new folder for the document. .Source folder ID (ECMID): A unique identifier of the present folder for the document. . .Include property definitions (Boolean): (Optional) An indicator that specifies whether type properties are to be returned. Remove document from folder Input: 837 . the default. means that the properties of the type are not to be included. .Document ID (ECMID): A unique identifier of a document.Object type definitions (ECMObjectTypeDefinition []): An array of type definitions. false. The ECMObjectTypeDefinition object contains the type metadata. Move document Input: .Target folder ID (ECMID): The identifier of the new parent folder. .Server name (String): The name of the server containing the document and folders. .Server name (String): The name of the ECM server that identifies the corresponding ECM repository.No output is returned. . returns all descendant types. -1. Output: ..No output is returned.Server name (String): The name of the server containing the object type. all root object types are returned. . Get type descendants Input: . Move folder Input: . Return type (String): (Optional) An indicator that determines the type of items returned by the search result.CMIS query (String): Text containing a Content Management Interoperability Services (CMIS) query. This parameter is only offered with the IBM BPM content store. The default is an object of type ECMSearchResultRow. If true then it considers the latest and older versions of the document or documents in the search. .Include allowable actions (Boolean): (Optional) An indicator that retrieves the available actions for the objects returned in the query. .Parent folder ID (ECMID): (Optional) The identifier of the parent folder. .Skip count (Integer): (Optional) An indicator that specifies the number of potential items to be skipped over before returning any items. then only the latest version is returned.Server name (String): The name of the server containing the document and folder. Set document content Input: 838 . If not specified.Business object name: When the name of a business object type is specified then an instance of that type is returned. .ECMSearchResultRow: (Default) An ECMSearchResultRow contains an array of values. Output: .No output is returned. Search Input: .Server name (String): The name of the server containing the documents and folders. . .Search all versions (Boolean): (Optional) An indicator that specifies which document versions are to be considered. the document is removed from all folders. . .Search result (ECMSearchResult): An object containing a set of qualifying items. which is the default.. The content is different based on the value of the Return type input parameter. . The default is 0.Document ID (ECMID): A unique identifier of a document. The default. The default is false. -1. The following types can be specified: . The properties returned by the search are mapped to the properties of the business object if their names match. states that the default number is taken from the ECM server. The name is the query name of the Content Management Interoperability Service (CMIS) property used in the SELECT clause of the query or the name can be determined by introspection of the metadata. Output: .Max items (Integer): (Optional) An indicator that specifies the maximum number of items to return. See Building a query for an Enterprise Content Management search operation. If false. Information about the ECMContentStream data type is found in the topic Working with document content.Document ID (ECMID): A unique identifier of a document.Document ID (ECMID): The unique identifier of the document. Output: . . Output: . Update document properties Input: . ..Server name (String): The name of the server containing the folder.Name (String): (Optional) A new name for the folder. Update folder properties Input: .Properties (ECMProperty []): (Optional) A set of named properties that can be in any order. . .Document ID (ECMID): An identifier of a document object.Properties (ECMProperty []): (Optional) A set of named properties that can be in any order.Content stream (ECMContentStream): The stream of data containing the content for the document such as a word processing document or an image. .Name (String): (Optional) A new name for the document. Parent topic:Outbound interactions with Enterprise Content Management systems Related information: Building a service that integrates with an ECM system or the IBM BPM document store 839 .Server name (String): The name of the server containing the document. .Document ID (ECMID): The unique identifier of a document.Folder ID (ECMID): The unique identifier of the folder. . Output: . The Set document content operation can only be used after running the Checkout document operation and before running the Check-in document operation.Folder ID (ECMID): An identifier of a folder object.Server name (String): The name of the server containing the document. . Business processes can instantiate. . Parent topic:Integrating with Enterprise Content Management (ECM) systems Related information: The IBM BPM document store The IBM BPM content store 840 . continue.Runtime behavior for inbound content events To work with inbound content events. or deletion of a document. you need to understand the runtime behavior of the events and you need to perform both modeling and administration tasks.Inbound events from Enterprise Content Management systems In IBM Business Process Manager.Performing administrative tasks for inbound events To receive information about inbound document and folder events that originate on Enterprise Content Management (ECM) servers. you need to perform the administrative tasks of developing and installing an event handler on your ECM system. you can create event subscriptions and design business processes and services that detect and respond to inbound content events from Enterprise Content Management (ECM) systems. The content events are used to catch and throw interactions with an ECM system. About this task To successfully receive and manage data from inbound content events that originate on Enterprise Content Management (ECM) servers. you should understand the two key concepts of runtime behavior: the event source ID and the filtering and processing of event subscriptions. such as creating the components that are required to handle. The event handler notifies the IBM BPM system about ECM events by calling the appropriate APIs. modification. or end based on the type of content event. you need to use Process Designer to perform the modeling tasks of creating and configuring components that can detect and respond to the content events. Information about the runtime behavior of content events and the required modeling and administrative tasks is found in the following topics: .Performing modeling tasks for inbound events To receive information about inbound content events that originate from changes to documents or folders on Enterprise Content Management (ECM) servers. detect. and respond to the events. . such as the creation. you should understand the two key concepts of runtime behavior: the event source ID and the filtering and processing of event subscriptions. which is generally a Globally Unique Identifier (GUID). Event source ID BPM may receive content events from multiple ECM systems and repositories. it also provides the event source ID for the corresponding ECM system. The event source ID maps to an ID that is native to the ECM system and that is retrieved by the Content Management Interoperability Services (CMIS) operation getRepositoryInfo. The event source ID is used to uniquely identify each ECM system and repository and to correlate incoming content events with event subscriptions.Runtime behavior for inbound content events To work with inbound content events. A query is used to match all incoming content events against all event subscriptions in all process applications according to the following criteria: . the event source ID maps to the object store ID (including the left brace and right brace characters). the attached service is started asynchronously and an instance of the ECMContentEvent business object is created. all matching event subscriptions are triggered that subscribe to the event and that belong to the following snapshots: .Default snapshot (Process Server) Each event subscription has an attached service that must include the ECMContentEvent business object as an input parameter. Parent topic:Inbound events from Enterprise Content Management systems 841 . These two concepts are described in the following sections. When BPM receives an inbound content event.Event source ID . the event source ID maps to the repository ID. When an ECM event handler sends content events to BPM. On all other ECM systems. On IBM FileNet Content Manager. When an event subscription is triggered.Tip (Process Center) . Filtering and processing of event subscriptions BPM supports a form of publish/subscribe (pub/sub) for content events. For any single inbound content event.Object type ID . there may be multiple event subscriptions that subscribe to the event.Event type The query returns the event subscriptions that match these criteria and that are enabled and authorized. The running service may invoke the undercover agent (UCA) that is attached to the Start Content Event or the Intermediate Content Event that is defined in the business process definition (BPD). you need to create several components in Process Designer. For example. you must create and configure a content undercover 842 . . it is generally recommended that you create all of the components at the same time by following the instructions in the topic Subscribing to document and folder events: the end-to-end approach. such as a content start or intermediate event. Although information about creating the required components is found in the modeling topics below. . you can create and configure an event subscription for a process application. you need to create an attached service that can be used to invoke a content undercover agent (UCA). About this task The following components are created as a result of performing the modeling tasks: . Using the end-to-end approach described in this topic.An attached service for the event subscription that will invoke the Content undercover agent (UCA) . you need to use Process Designer to perform the modeling tasks of creating and configuring components that can detect and respond to the content events.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 will find that creating the required components is more automated and less complex than creating them one at a time on a stand-alone basis.Subscribing to document and folder events: the end-to-end approach To detect and respond to document and folder events that are produced when content changes occur on an Enterprise Content Management (ECM) server.Creating and configuring event subscriptions In IBM® Process Designer. . . . which will catch or throw interactions with an ECM server.An event subscription for the process application .A Content UCA to trigger a content event . This is a simpler approach than creating each component separately on a stand-alone basis and it automatically creates some resources that you would otherwise need to create manually.Creating attached services To enable an event subscription to respond to events from your Enterprise Content Management server. you must specify the type of content event that you want to receive when a specific content change occurs on an Enterprise Content Management (ECM) server.Content event types When you configure an event subscription in Process Designer. if you want an event to be received when a user creates a document on an ECM server. which is used to obtain information about document and folder events that occur on an Enterprise Content Management (ECM) server.A content event for the business process definition (BPD). you would select the Created event type.Performing modeling tasks for inbound events To receive information about inbound content events that originate from changes to documents or folders on Enterprise Content Management (ECM) servers. or event subprocess start event. but it has a specialized Content marker to differentiate it from a Message marker. boundary event. mapped. The ECMContentEvent business object is used to pass generic ECM event data to an event subscription service and content undercover agent (UCA). The business object is passed unchanged as BPMN event data into the process if it is not modified.agent that works with your event subscription. intermediate event.The ECMContentEvent business object The ECMContentEvent business object is included in the Content Management toolkit. which is used to gain access to Enterprise Content Management (ECM) types and services. . or replaced by the service or UCA. such as a start event. Parent topic:Inbound events from Enterprise Content Management systems 843 . . It is conceptually similar to a message undercover agent. a content event is used to catch or throw interactions with an enterprise content management (ECM) system. The resources of the toolkit are required to allow a business process developed in Process Designer to work with an Enterprise Content Management system. A content undercover agent (UCA) is used to initiate a BPM Start or Intermediate event when specific content changes occur on an ECM server.Adding a content event to a BPD In a BPD. You can add one of several types of content events. you perform the following activities in Process Designer (in the order in which they are listed): ." F. you will find that creating the required components is more automated and less complex than creating them one at a time on a standalone basis. B. The new event subscription is displayed in the Implementation library list (under Event Subscription) and the event subscription opens in the Event Subscription editor.Subscribing to document and folder events: the end-to-end approach To detect and respond to document and folder events that are produced when content changes occur on an Enterprise Content Management (ECM) server. complete the following procedure: Procedure 1. Open a process application in Process Designer. Information about adding an ECM server is found in the topic "Adding an Enterprise Content Management server.Add an attached service and a Content undercover agent (UCA) . The New Event Subscription wizard opens. In the library area of the Designer page. Using the end-to-end approach described in this topic. About this task In the end-to-end approach. click Save and then switch to the event subscription editor again and select the server from the ECM Server drop-down list. If you selected the name of an ECM server in the ECM Server drop-down list. After adding the server. Click Finish.The name of an ECM server Information about the IBM BPM document store is found in the topic "Working with IBM BPM documents." If you want to select the name of an ECM server but no ECM servers are available for selection. C. D. E.Create an event subscription . specify a name for the new event subscription. In the ECM Server drop-down list.Test the new components To perform these activities. select either the default Document event class or the Folder event class in 844 . Create an event subscription by completing the following steps: A.Add a content event to a business process definition (BPD) . you need to create several components in Process Designer. select one of the following server types to associate with the event subscription: .IBM BPM document store . you can add a server in the Process App Settings editor by selecting the Use the Process Application Settings editor to add a server link and then clicking the Servers tab. In the Name field. click the plus (+) icon beside Implementation and then select Event Subscription. the Event Class drop-down list. 2. you can create a new team for designated users by completing the following steps: 1. The new service and a new content UCA of the same name are automatically created. However. I. accept the default Created event type for your ECM server or select a different event type. if you want to create an integration service that will first query the ECM server for additional information before determining whether a UCA should be invoked. This is accomplished by clicking Select in the Exposing area and then choosing the name of the team. Add an attached service and a Content UCA by completing the following steps: A. G. If you selected the IBM® BPM document store in the ECM Servers drop-down list. Click Finish. and an Invoke UCA step to invoke 845 . 3. (If the drop-down list is disabled. an End event. click New. By default. Click Save. select Create a service that queries the ECM server before invoking a Content UCA. In the Name field. select Create a service that directly invokes a UCA. If you want to create a general system service that will directly invoke the Content UCA without first querying the ECM server for additional information. you cannot change the default behavior of event subscriptions being exposed to all users. In the Team page. select either the top-level default Document object type or select a different object type in the Object Type drop-down list. In the Attached Service area. if you chose to create an integration service. 4. such as an Integration step. a decision gateway step. Click Finish. If you selected the name of an ECM server in the ECM Server drop-down list and you want to include all of the subtypes of the selected object type. if you selected the name of an ECM server in the ECM Servers drop-down list. In the Name field. The new service opens in the service editor. define the team by following the instructions in the topic Creating a team. K. event subscriptions are exposed to all users. In the Event Type drop-down list. C. the server is probably unavailable.If you chose to create a general system service. it is partially implemented and it consists of several components. the server is probably unavailable. The New Service for Event Subscriptions wizard opens. In the Exposing area. The New Team wizard opens. D. accept the default name (which is the same as the event subscription name) or type a different name for your new service. However. click New. B. you can specify that you only want events to be fired for designated users who are named in an existing team. However. and an Invoke UCA step that will invoke the new Content UCA. 2. (If the drop-down list is disabled. This means that when any user performs an action that corresponds to the event type that is specified in the Event Type drop-down list (such as creating a document). type a name for the new team. ensure that the Include Subtypes check box is selected. a document event or a folder event will be fired. If you selected the name of an ECM server in the ECM Server drop-down list.) H. J.) Information about the available event types is found in the topic Content event types. Alternatively. it is already fully implemented and consists of a Start event. The Team page opens. The Data Mapping panel opens. The event in the diagram changes to display a Content marker icon. The Implementation panel opens. 3. (Additional information about creating a Content UCA is found in the topic Creating and configuring an undercover agent for a content event. click Select and then select the Content UCA that was automatically created when you created the attached service. specify a name for the new BPD. E. In the canvas. Add a content event to a BPD by completing the following steps: A. Click Save. select the decision gateway in the canvas and open the Properties tab and the Implementation pane. the signature of both the service and the Content UCA includes an Input named contentEvent with a business object type of ECMContentEvent. Click Finish. ensure that the Content event is selected. In the library area of the Designer page. select the existing Start event or select the Start Event or Intermediate Event icon in the palette and drag the event to the canvas. In the Start Event Details or Intermediate Event Details section.the Content UCA. this is all that is required to complete the implementation of the integration service. F. D. then define the decision conditions for the decision gateway. F. The following figure shows an integration service as it might appear after it has been fully implemented: For both a general system service and an integration service. If you chose to create an integration service. In the Name field. Beside the Attached Content UCA area in the Content Trigger section. In the canvas. B. The new BPD is displayed in the Process library list (under Business Process Definitions) and the BPD opens in the BPD editor. G. click the plus (+) icon beside Processes and then select Business Process Definition. The New Business Process Definition wizard opens. C. Click the Properties tab and then click Implementation. then click the Properties tab and click Data Mapping. 846 . It has the same name as the service. Other than perhaps renaming the labels of the components. change None to Content.) H. E. ) K. Click Save. 4. This correlation ensures that the parameter values of the runtime message are passed to the correct BPD instance. If you are working with an intermediate event. 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. The variable selected for correlation is identified by an assignment symbol. select the variable that you want to use to correlate the event with the BPD instance. You can view BPD instances in the Inspector view of Process Designer. Switch to your event subscription in the event subscription editor. Parent topic:Performing modeling tasks for inbound events 847 . Test Event Subscription opens. If the event subscription is defined correctly. accept the default object or select a different object on the ECM server. C. a simulated incoming ECM event is triggered and the following message is displayed: An inbound ECM event has been successfully simulated for the event subscription. D. Click Test. which leads to either a response from an existing BPD instance or the creation of a new BPD instance. J. The attached service. and start or intermediate event are subsequently invoked. which contains fields that are populated with the selections that you made in the Event Subscription editor. Test the new components by completing the following steps: A. content UCA. Click Test Subscription.I. (IBM Business Process Manager only requires one variable mapping to correlate the event. In the Object field. The selections represent the data that will be returned from the ECM server. B. E. Click Save. In the Name field. In the library area of the Designer page. D. Open a process application. This is a simpler approach than creating each component on a standalone basis and it automatically creates some resources that you would otherwise need to create manually. In the ECM Server drop-down list. you can create and configure an event subscription for a process application. you must be in the IBM Process Designer desktop editor. It is used for developing case management applications." 848 . 3. Before you begin This topic describes how to create an event subscription without consideration for some of the other components that are required to detect and respond to ECM events. It is only available in IBM Business Process Manager Advanced. C. click the plus (+) icon beside Implementation and then select Event Subscription. select one of the following server types to associate with the event subscription: . .The name of an ECM server Information about the IBM BPM document store and the IBM BPM content store is found in the topic "Working with IBM BPM documents. It is used in developing business process definitions. specify a name for the new event subscription. .Creating and configuring event subscriptions In IBM® Process Designer. which is used to obtain information about document and folder events that occur on an Enterprise Content Management (ECM) server. complete the instructions in the following procedure. The IBM BPM content store supports all CMIS operations. About this task To create and configure an event subscription. you should follow the instructions in the topic Subscribing to document and folder events: the end-to-end approach. Click Finish.IBM BPM content store. 2. Create a new event subscription by completing the following steps: A. If you need to create an event subscription and all of the other required components as well. Procedure 1. The New Event Subscription wizard opens. The IBM BPM document store supports most Content Management Interoperability Services (CMIS) operations.To perform this task. Open the Process Designer desktop editor. such as a content undercover agent (UCA). B. The new event subscription is displayed in the Implementation library list (under Event Subscription) and the event subscription opens in the Event Subscription editor.IBM BPM document store. Configure the new event subscription by completing the following steps in the Event Subscription editor: A. select either the default Document event class or the Folder event class in the Event Class drop-down list. if you want to create an integration service that will first query the ECM server for additional information before determining whether a UCA should be invoked. Information about adding an ECM server is found in the topic "Adding an Enterprise Content Management server. E. If you want to create a new service for your event subscription that will run and respond to incoming ECM events. F. and an Invoke UCA step to invoke the content UCA. However. However. (If the drop-down list is disabled. In the Name field. click Select in the Attached service area and then select the name of a service. Click Finish. C. If you selected the name of an ECM server in the ECM Server drop-down list. 4. you can add a server in the Process App Settings editor by selecting the Use the Process Application Settings editor to add a server link and then clicking the Servers tab. After adding the server. such as an Integration step. it is already fully implemented and consists of a start event. accept the default name (which is the same as the event subscription name) or type a different name for your new service. If you want to create a general system service that will directly invoke the content UCA without first querying the ECM server for additional information. see Content event types. In the Event type drop-down list. select Create a service that directly invokes a UCA. click Save and then switch to the event subscription editor again and select the server from the ECM Server drop-down list. the server is probably unavailable. In the Attached Service area. G. The new service opens in the service editor. select either the top-level default Document object type or select a different object type in the Object Type drop-down list. 2. ensure that the Include Subtypes check box is selected. complete the following steps: 1. click New. If you selected the name of an ECM server in the ECM Server drop-down list. The new service and a new content UCA of the same name are created. If you selected the name of an ECM server in the ECM Server drop-down list and you want to include all of the subtypes of the selected object type.) For more information about the available event types. If you chose to create a general system service. The New Service for Event Subscriptions wizard opens. a decision gateway step.) D. it is partially implemented and it consists of several components. select Create a service that queries the ECM server before invoking a Content UCA. accept the Created default event type for your ECM server or select a different event type. an end event. 3. (If the drop-down list is disabled.If you want to select the name of an ECM server but no ECM servers are available for selection." B. such as General System Service or Integration Service. and an Invoke UCA step that will invoke the new content UCA. If you want to select an existing service for your event subscription that will run and respond to incoming ECM events. 849 . if you chose to create an integration service. the server is probably unavailable. 4. In the Exposing area. Test Event Subscription opens. Click Test. Alternatively. 3. Click Test Subscription. The attached service. The selections represent the data that will be returned from the ECM server. If you want to test your event subscription and ensure that the attached service. The New Team wizard opens. 3. you can create a new team for designated users by completing the following steps: 1. The Team page opens. In the Object field. click New. By default. However. which contains fields that are populated with the selections that you made in the Event Subscription editor. a simulated incoming ECM event is triggered and the following message is displayed: An inbound ECM event has been successfully simulated for the event subscription. 2. I. content UCA. for the IBM BPM content store or an ECM server in the ECM Servers dropdown list. If you selected the IBM BPM document store in the ECM Servers drop-down list. you cannot change the default behavior of event subscriptions being exposed to all users. In the Name field. and start and intermediate events are all operating correctly. Click Save. This is accomplished by clicking Select in the Exposing area and then choosing the name of the team. Click Finish. complete the following steps: 1. You can view BPD instances in the Inspector view of Process Designer. which leads to either a response from an existing BPD instance or the creation of a new BPD instance. J. a document event or a folder event will be fired. content UCA. event subscriptions are exposed to all users. This means that when any user performs an action that corresponds to the event type that is specified in the Event Type drop-down list (such as creating a document). Parent topic:Performing modeling tasks for inbound events Related information: Building a service that integrates with an ECM system or the IBM BPM document store Working with IBM BPM documents Adding an Enterprise Content Management server 850 .H. define the team by following the instructions in the topic Creating a team. If the event subscription is defined correctly. type a name for the new team. accept the default object or select a different object on the ECM server. and start or intermediate event are subsequently invoked. you can specify that you only want events to be fired for designated users who are named in an existing team. 2. In the Team page. However. The following table lists the types of content events that you can select when you configure an event subscription in Process Designer. Classify Completed Documents An event produced when a document is added using an entry template with the Auto-Classify option set. you must specify the type of content event that you want to receive when a specific content change occurs on an Enterprise Content Management (ECM) server. Class Changed Folders or documents An event produced when a user changes the class of the object. Created Folders or documents An event produced when a user adds an item to the object store. On IBM FileNet Content Manager. the user can change the class when checking in a document. For example. Check Out Canceled Documents An event produced when a user cancels the checkout of a document. Content events Content event types Checked In Associated object types Documents Description An event produced when a user checks in a document. you would select the Created event type. on other ECM systems. Checked Out Documents An event produced when a user checks out a document. all of these event types are supported and an event handler is provided. For example. if you want an event to be received when a user creates a document on an ECM server. 851 . Information about how to develop an event handler for the supported event types is found in the topic Creating an event handler for an Enterprise Content Management system. Table 1.Content event types When you configure an event subscription in Process Designer. some of the event types are not supported and you need to develop your own event handler. if a user deletes a document that has ten versions. Folders or documents An event produced when an item is locked for use by a custom application. When a document is deleted. a document or custom object) or when the file is called to create a subfolder. a workflow is launched for each item in the version series. Documents An event produced when a publish request for a document is completed.Deleted Filed Frozen Locked Publish Completed Publish Requested Folders or documents An event produced when a user deletes an item. For example. 852 . Documents An event produced when an administrator or application freezes the custom properties of a specific document version. Folders An event produced when a folder has its file method called to file a Containable object (for example. Documents An event produced when a publish request for a document is initiated. ten workflows are launched. Note: An Updated event is triggered each time a new item is created. a document or folder) or when the unfile method is called to delete a subfolder. security for a document can be changed from the information page or when:Adding a documentChecking in a documentPromoting a version of a document Documents An event produced when the state of the document changes.Security Updated State Changed Unfiled Unlocked Updated Folders or documents An event produced when a user changes the security of the object. As a result. For example. such as when a version is promoted or demoted. 853 . a workflow set to use the update trigger is launched when a user adds a new document. Folders An event produced when a folder has its unfile method called to remove (unfile) a Containable object (for example. Folders or documents An event produced when an item is unlocked for use by a custom application. Folders or documents An event produced on any action that updates the property values or content of an item. Behavior will vary depending on the object and the action. you can create subscriptions with the Publish Request event using Enterprise Manager for the Content Engine. If you need to use these triggers. Note: The Filed and Unfiled event triggers are not supported for subscriptions. Parent topic:Performing modeling tasks for inbound events 854 .Version Demoted Documents Version Promoted Documents An event produced when a document version is demoted. The document can be promoted to a released version from the information page or when adding or checking in. you can create the subscription using the Enterprise Manager for the Content Engine. In addition. An event produced when a document version is promoted to a released version. There are two kinds of attached service that you can create: . Information about creating these two kinds of services is found in Building an Integration service and Building a General System service. About this task It is generally recommended that you create an attached service at the same time as the other required components by following the instructions in the topic Subscribing to document and folder events: the end-to-end approach.Creating attached services To enable an event subscription to respond to events from your Enterprise Content Management server.If you want to create an attached service that will first query the ECM server for additional information before determining whether a UCA should be invoked. you need to create an attached service that can be used to invoke a content undercover agent (UCA). This is a simpler approach than creating each component on a stand-alone basis and it automatically creates some resources that you would otherwise need to create manually. However. . Parent topic:Performing modeling tasks for inbound events 855 . then you should create an integration service. you can also create an attached service on its own without any consideration for some of the other components that are required to detect and respond to ECM events.If you want to create an attached service that will directly invoke a content UCA without first querying the ECM server for additional information. then you should create a general system service. Open the Process Designer desktop editor.Adding a content event to a BPD In a BPD. Click the Properties tab and then click Implementation.) Alternatively. ensure that the Content event is selected. you should follow the instructions in the topic Subscribing to document and folder events: the end-to-end approach. Beside the Attached Content UCA area in the Content Trigger section. 5. or event subprocess start event. intermediate event. then click the Properties tab and click Data Mapping. you can click New to create a content UCA. such as an event subscription. The new BPD is displayed in the Process library list (under Business Process Definitions) and the BPD opens in the BPD editor. click Select to select an existing content undercover agent (UCA). (If you select an existing message UCA. you can also add a content event to a new BPD by completing the following steps: Procedure 1. The Data Mapping panel opens. change None to Content. For information about creating content UCAs. you must be in the IBM® Process Designer desktop editor. You can add one of several types of content events. In the canvas. If you need to add a content event to a BPD and create all of the other required components as well. This is a simpler approach than creating each component on a standalone basis and it automatically creates some resources that you would otherwise need to create manually. 8. Click the plus (+) icon beside Processes and then select Business Process Definition. see Creating and configuring an undercover agent for a content event. Open a process application in the Designer view. specify a name for the new BPD. 6. The New Business Process Definition wizard opens. select the existing Start event or select the Start Event or Intermediate Event icon in the palette and drag the event to the canvas. The Implementation panel opens. In the Name field. About this task Although you can add a content event to an existing BPD. 9. 856 . a content event is used to catch or throw interactions with an enterprise content management (ECM) system.To perform this task. such as a start event. In the BPD editor canvas. The event in the diagram changes to display a Content marker icon. the intermediate event in the diagram is changed from a content event to a message event. 10. 4. 2. boundary event. Click Finish. Before you begin This topic describes how to add a content event to a BPD without consideration for some of the other components that are required to detect and respond to ECM events. 7. 3. In the Start Event Details or Intermediate Event Details section. Click Save. 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. Parent topic:Performing modeling tasks for inbound events 857 .) For undercover agents that are implemented using a complex variable rather than a service. (IBM Business Process Manager only requires one variable mapping to correlate the event. B. The variable selected for correlation is identified by an assignment symbol ( ). Perform the data mapping tasks by completing the following steps: A. If you are working with an intermediate event. you can select the complex variable or the top-level child properties of the variable for mapping or correlation. This correlation ensures that the parameter values of the runtime message are passed to the correct BPD instance. 12.11. select the variable that you want to use to correlate the event with the BPD instance. The resources of the toolkit are required to allow a business process developed in Process Designer to work with an Enterprise Content Management system. you can use a content integration step in the service to retrieve more information about the object in the ECM server. such as additional properties for the specified document or folder.ECMEventClass eventClass: The class of the event. . or replaced by the service or UCA.ECMEventType eventType: The type of event that occurred on the folder or document.ECMID objectId: The object ID of the folder or document on which the event occurred. which is either "document" or "folder".ECMID repositoryId: The object ID of the repository. mapped. . .The ECMContentEvent business object The ECMContentEvent business object is included in the Content Management toolkit. . In addition to the data included in the ECMContentEvent business object. The properties for the ECMContentEvent business object are described in the following list: .ECMID objectTypeId: The object ID of the folder type or the document type. . which is used to gain access to Enterprise Content Management (ECM) types and services.String serverName: The name of the ECM server. The ECMContentEvent business object is used to pass generic ECM event data to an event subscription service and content undercover agent (UCA). Parent topic:Performing modeling tasks for inbound events 858 . an ECMContentEvent business object is passed to the service that is attached to the event subscription. The business object is passed unchanged as BPMN event data into the process if it is not modified. When an event subscription is triggered. These events can be received by processes on your IBM BPM system. Parent topic:Inbound events from Enterprise Content Management systems 859 . you need to perform the administrative tasks of developing and installing an event handler on your ECM system. The event handler notifies the IBM BPM system of the events by calling the appropriate IBM BPM APIs. and configure it to provide notification events to your IBM BPM processes.Using the event handler for FileNet Content Manager You can deploy the event handler on a IBM® FileNet® Content Manager system. However. you must install an event handler on the ECM system.Performing administrative tasks for inbound events To receive information about inbound document and folder events that originate on Enterprise Content Management (ECM) servers. you need to both develop and install an event handler.Information about developing and installing event handlers is found in the following topics: . About this task For most ECM systems. . if you are using IBM Filenet Content Manager.Creating an event handler for an Enterprise Content Management system To obtain information about content events that occur on an Enterprise Content Management (ECM) server. an event handler is already provided and you only need to install it. The event handler notifies the IBM BPM system about ECM events by calling the appropriate APIs. refer to the FileNet Content Manager information center topics Events and Subscriptions. Identify which ECM events you need your event handler to support.Table 1. you do not need to write your own event handler. To understand the concepts behind the FileNet Content Manager event handler. The following table lists the IBM BPM names for the ECM events that are supported by IBM BPM. Procedure 1. Tip: You can find the source files for the FileNet Content Manager event handler in install_root\BPM\EventHandlers\ECM\FileNet\filenet-bpm-event-handler- 51-src. About this task . . you must install an event handler on the ECM system. you only need to perform the actions described in Using the event handler for FileNet Content Manager.Creating an event handler for an Enterprise Content Management system To obtain information about content events that occur on an Enterprise Content Management (ECM) server. The event handler notifies the IBM BPM system of the events by calling the appropriate IBM BPM APIs.If you do not use FileNet Content Manager you must write your own event handler for your ECM system.jar.If you use IBM® FileNet® Content Manager. ECM events supported by IBM BPM Supported ECM events CheckedIn CheckedOut CheckOutCanceled ClassChanged ClassifyCompleted Created Deleted Filed Frozen Locked PublishCompleted PublishRequested SecurityUpdated StateChanged Unfiled Object types that the event can apply to Document Document Document Folder or Document Document Folder or Document Folder or Document Folder Document Folder or Document Document Document Folder or Document Document Folder 860 . Familiarize yourself with your ECM system and its framework for implementing and configuring an event handler. These events can be received by processes on your IBM BPM system. Plan for the specific requirements of your ECM system. 3. the FileNet Content Manager event handler. Parent topic:Performing administrative tasks for inbound events Related reference: REST API: ECM Event Resource . Perform Creating and configuring event subscriptions. Plan your code to receive event notifications in your ECM system and translate them into the corresponding calls to the appropriate IBM BPM system.POST Method Related information: Adding an Enterprise Content Management server Building a service that integrates with an ECM system or the IBM BPM document store Adding events to a BPD 861 . 7. loads the connection information defined in a properties file that is stored in FileNet Content Manager. For example. Plan how your ECM event handler will obtain the information required to connect to the IBM BPM system. Deploy and configure your event handler on your ECM system. 4. For example. For each event that you need notifications of.Unlocked Updated VersionDemoted VersionPromoted Folder or Document Folder or Document Document Document Tip: For more details about the event types. identify the corresponding event name that is used by your ECM system. 8. 6. and that it transmits the events to the appropriate IBM BPM server. in the FileNet Content Manager event handler BPMEventHandler. 2. Verify that your event handler is called for the required events. Write your event handler according to your requirements and the event handling framework provided by your ECM system. Verify that you can create an IBM BPM process that receives the event notifications from your ECM system. BPMEventHandler. 5. refer to the REST API ECM event resource reference topic. Refer to the documentation for your ECM system. the BPMEventType method translates the FileNet Content Manager event types to the corresponding IBM BPM event notification API method names. Use the table to identify the FileNet Content Manager events that you need to subscribe to. and the names that are used in Process Designer to identify the same events in IBM BPM. Mapping between supported ECM events and FileNet Content Manager events ECM events Object types that the supported by IBM event can apply to BPM (com.BPME ventType) CheckedIn Document CheckedOut Document CheckOutCancelled Document ClassChanged Folder or Document ClassifyCompleted Document Created Deleted Filed Frozen Locked PublishCompleted Folder or Document Folder or Document Folder Document Folder or Document Document PublishRequested Document SecurityUpdated Folder or Document StateChanged Unfiled Unlocked Updated VersionDemoted Document Folder Folder or Document Folder or Document Document VersionPromoted Document 862 Corresponding FileNet Content Manager events (com. Supported events The following table lists all ECM events that are supported by IBM BPM.1. and configure it to provide notification events to your IBM BPM processes. Overview The event handler is for IBM FileNet Content Manager version 5.filenet.api.bpm.ibm. Table 1.event s) CheckinEvent CheckoutEvent CancelCheckoutEve nt ChangeClassEvent ClassifyCompleteE vent CreationEvent DeletionEvent FileEvent FreezeEvent LockEvent PublishCompleteEv ent PublishRequestEve nt UpdateSecurityEve nt ChangeStateEvent UnfileEvent UnlockEvent UpdateEvent DemoteVersionEven t PromoteVersionEve nt .Using the event handler for FileNet Content Manager You can deploy the event handler on a IBM® FileNet® Content Manager system. and the corresponding FileNet Content Manager events. for example. For example: bpm. .If you have a suitable J2C authentication alias defined on the application server where FileNet Content Manager is running. create a properties file. For details about how to create an event subscription in Process Designer.jar Copy the event handler to a suitable location on your FileNet Content Manager server. and bpm_server_name is the host name or IP address of your IBM BPM server.server. For a simple end-to-end verification test.If you do not use an authentication alias. Copy the event handler to your FileNet Content Manager server The event handler is in the following location on your IBM BPM server: install_root/BPM/EventHandlers/ECM/FileNet/filenet-bpmevent-handler-51.server.uri=http\://bpm_server_name\:9080 Where scope is the scope of the authentication alias my_authentication_alias. you might want to create a test process to consume the notifications. On your FileNet Content Manager server. it makes sense to include the name of the server in the name of the properties file. Creating the connection information document The connection information necessary for the ECM event handler to connect to the IBM BPM system is stored as a document in the FileNet Content Manager repository. and bpm_server_name is the host name or IP address of your IBM BPM server. Although you can give the properties file any name. perform the following steps: 1.server. For example:bpm.properties. Tip: If you require multiple subscriptions that notify different IBM BPM servers of events.example. bpmserver1.com.server.password=bpm_user_password bpm. bpm1. 863 . for example.Define a process to consume the ECM events Before you configure the event handler to generate event notifications on your IBM BPM system. To create the connection information document.server. bpm_user_password is the password for the user ID. you need one properties file for each IBM BPM server. for example. your server connection properties file must specify a suitable IBM BPM user name and password. refer to Creating and configuring event subscriptions.jar install_root\BPM\EventHandlers\ECM\FileNet\filenet-bpm-eventhandler-51.username=bpm_user bpm. you can define the connection properties file to use the authentication alias. when you use the content integration control.Tip: In Process Designer. the value that you specify for the Object Type must match the name of the document class you select when creating the subscription on the FileNet Content Manager server. for example. consider subscribing to one event that is not triggered too often. the Updated event for folders. .authalias=scope/ my_authentication_alias bpm.uri=http\://bpm_server_name\:9080 Where bpm_user is a user ID that is authorized to access the IBM BPM. A. There are several ways that you can store the properties file.. Using a browser. 3. 2. Add a subscription to the class and bind the subscription to the event handler. or select and copy it to a convenient clipboard or text file. then click Next. On the local file system. select it. Using the FileNet Enterprise Manager. for example life_insurance_applications. For example. Specify that the subscription applies to all instances of the class. then Next. The default object stores are DESIGN and TARGET. 864 . then Add. for example. If the document class or folder class that you want to receive event notifications for does not yet exist. locate the properties file. Expand the object store. Make a note of the document ID. Remember: In Process Designer when you use the content integration control. Make a note of the document ID for the properties file. perform one of the following. you can use the Workplace XT portal to store the properties file by performing the following actions: A. a Symbolic Name. you must use this class name for the Object Type. bpmserver1. . create a suitable class by performing the following actions. Click Choose File. C.bpm1. Remember: You must specify this document ID later when you configure the binding of the event handler to the event subscription.To create a new folder class. C. Select the same object store where the case solution is located. action or icon. To create the new class. right-click the appropriate document class or folder class. and select Add Subscription. click Next.To create a new document class. B. Enter a Name and Description for the new subscription. B. and click Next. perform the following actions.com. F. E. Click OK. 2. Repeatedly select a required event and add it to the Subscribed Events list by clicking Add. A. right-click Document class. 1. D. Select the object store where you want to store the configuration file. Creating a subscription and binding it to the event handler Add a subscription for the events that you want to be sent to your IBM BPM system. then either add a new folder or select a suitable existing folder where you want to store the properties file. B. A. For example. Enter the Name. log in to the Workplace XT portal at the URL http:// filenet_server_host_name:port/WorkplaceXT. and a Description for the new class. and select Properties. Right-click the name of the properties file that you stored. right-click Folder. Store the properties file in the ECM system. DESIGN or TARGET. C. When all required events are in the Subscribed Events list. For example. and select New Class. . Click the Add Document. Using the FileNet Enterprise Manager. if you are using the Workplace XT portal. and select New Class. and click OK. B. Add the required events from the Available Events list to the Subscribed Events list.example. D.. expand Other Classes.properties. expand the object store where the case solution resides. for example.. 2. Click Properties. B. For Handler Java Class Name. Click OK. Click Browse/Add to locate the event handler JAR file filenet-bpmevent-handler-51. button. Click Finish to complete creating the subscription. E.BPMEventHandler. Remember: If you ever modify the connection information in the properties file. you will have a connection properties file for each IBM BPM server. and click Next. If you already created an event action for the BpmEventHandler event handler. Click New. D.E.ibm. F. Click the .POST Method Related information: Adding an Enterprise Content Management server Building a service that integrates with an ECM system or the IBM BPM document store Adding events to a BPD 865 .Important: If you want different IBM BPM servers to receive event notifications. then click Next. 3. Parent topic:Performing administrative tasks for inbound events Related reference: REST API: ECM Event Resource . G. C.bpm. because the new version gets a new document ID.jar that you copied from your IBM BPM server. Verify that the newly created event action is selected. Click OK. you must change the User String to identify the new document ID. 4. This is the string that you noted during Creating the connection information document.integration. enter com. A. Accept the default settings in Specifiy Additional Properties by clicking Next. select Configure Code Module. Now notifications of all subscribed events are sent to the appropriate IBM BPM server. Make sure that you provide the document ID for the appropriate server's connection properties file.. then click Next. locate the property with the Property Name of User String. enter an appropriate name for the action event. then click Next. Set the User String property for the subscription to the document ID for the properties file. F. Otherwise. BpmEventHandler. In the list of properties. and click Next. In the Subscription Name list. Finish. and enter (or preferably copy and paste) the value of the document ID for the properties file. select the subscription that you named in step 2b.filenet. create a new event action for the BpmEventHandler event handler by performing the following steps: 1. select it using the drop-down list. 3. 866 . A connection cannot be established to an ECM system A connection must be established through Content Management Interoperability Services (CMIS) using the web services protocol rather than the Atom protocol. parameters that are marked as optional may actually be mandatory for some ECM systems. the Content Management Interoperability Services (CMIS) specification is used to determine which operation parameters are marked as optional. the optional Content stream (ECMContentStream) parameter is used to pass a stream of data containing the content of the document.Operation parameters that are considered optional in Process Designer may be mandatory in some ECM systems These issues are discussed in the following sections.A connection cannot be established to an ECM system . When you add an ECM server. Some known issues are: .Troubleshooting interactions with Enterprise Content Management systems From time to time. However. Parent topic:Integrating with Enterprise Content Management (ECM) systems 867 . In most situations. you cannot pass the content stream parameter with the Check-in document operation. However. if you have made updates to a document and your ECM system is Microsoft SharePoint. such as a word processing document or an image. You can consult your ECM system documentation to determine whether a parameter is optional or mandatory for your ECM system. you can successfully work around these issues. Operation parameters that are considered optional in Process Designer may be mandatory in some ECM systems In Process Designer. The use of the "Check-in document" operation differs on Microsoft Sharepoint In the Check-in document operation. You must first pass the content stream parameter with the Set document content operation and then you can use the Check-in document operation. ensure that the context path specifies the path to the CMIS web services application on the server. you may encounter some issues during interactions with Enterprise Content Management (ECM) systems. such as their CMIS capabilities and limitations. The integration considerations for supported ECM products are described in the following topics: .4.1 Content Manager.2. . Parent topic:Integrating with Enterprise Content Management (ECM) systems 868 .Integration considerations for IBM FileNet Content Manager IBM BPM supports ECM integration with IBM FileNet 5.Integration considerations for ECM products To work with specific ECM products.Integration considerations for IBM Content Manager IBM BPM supports the ECM integration with IBM Content Manager 8.Integration considerations for Alfresco Community IBM BPM supports the ECM integration with Alfresco Community 4. .3. it is helpful to have an understanding of their main integration considerations.Integration considerations for Microsoft SharePoint IBM® BPM supports ECM integration with Microsoft SharePoint 2010. . the default CMIS web service context path is "/fncmis".Integration considerations for IBM FileNet Content Manager IBM BPM supports ECM integration with IBM FileNet 5. Other integration considerations for IBM FileNet Content Manager are described in the following sections: .CMIS capabilities .Best practices . When you define the ECM server properties for IBM FileNet Content Manager.1 Content Manager. Reference 869 . You can contact your IBM FileNet Content Manager administrator for complete connection information.Reference CMIS capabilities IBM FileNet Content Manager supports the optional CMIS capabilities that are described in the following table: CMIS Capability IBM FileNet Content BPM Considerations Manager ACL none Not applicable AllVersionsSearchabl true e Changes none Not applicable ContentStreamUpdat pwconly Documents must be ability checked out for updates GetDescendants true GetFolderTree true Join innerandouter Multifiling true PWCSearchable true PWCUpdatable true Query metadataonly The CONTAINS() predicate function is not supported Renditions none Not applicable Unfiling true VersionSpecificFiling false Best practices The best practices for developing client applications for IBM CMIS for FileNet Content Manager are described in the topic Best practices for developing client applications. Information about the IBM CMIS for FileNet Content Manager implementation of the OASIS CMIS standard is found in the topic IBM CMIS for FileNet Content Manager implementation of the OASIS CMIS specification. Parent topic:Integration considerations for ECM products 870 . 4.CMIS capabilities .Known limitations .Reference CMIS capabilities IBM Content Manager supports the optional CMIS capabilities that are described in the following table: CMIS Capability IBM Content Manager ACL none AllVersionsSearchabl true e Changes none ContentStreamUpdat pwconly ability GetDescendants GetFolderTree Join true true none Multifiling PWCSearchable true false PWCUpdatable false Query metadataonly BPM Considerations Not applicable Not applicable Documents must be checked out for updates Queries cannot include any JOIN clauses Renditions none Unfiling true VersionSpecificFiling false Private working copies of a document are not searchable The private working copy of a document is not updatable The CONTAINS() predicate function is not supported Not applicable Known limitations The known limitations of the IBM CMIS for Content Manager implementation are described in the topic IBM CMIS for Content Manager limitations.Other integration considerations for IBM Content Manager are described in the following sections: . When you define the ECM server properties for IBM Content Manager.Integration considerations for IBM Content Manager IBM BPM supports the ECM integration with IBM Content Manager 8. You can contact your IBM Content Manager administrator for complete connection information.3. the default CMIS web service context path is "/cmcmis". 871 . Reference Information about the IBM CMIS for Content Manager implementation of the OASIS CMIS standard is found in the topic Programming IBM CMIS for Content Manager applications. Parent topic:Integration considerations for ECM products 872 . 2. 873 . Other integration considerations for Alfresco Community are described in the following sections: .Integration considerations for Alfresco Community IBM BPM supports the ECM integration with Alfresco Community 4.Reference Capabilities Alfresco Community supports the optional CMIS capabilities that are described in the following table: CMIS Capability ACL AllVersionsSearchabl e Changes ContentStreamUpdat ability GetDescendants GetFolderTree Join Alfresco Community manage false BPM Considerations Not applicable none anytime Not applicable Multifiling PWCSearchable true false PWCUpdatable Query Renditions Unfiling true bothcombined read false true true none Queries cannot include any JOIN clauses Private working copies of a document are not searchable Not applicable Documents are always filed in a folder VersionSpecificFiling false Deviations from the CMIS standard Alfresco deviates from the OASIS CMIS standard in the following ways: . the default CMIS web service context path is "/alfresco/cmisws".CMIS capabilities .The ECM operation Remove Document From Folder (CMIS removeObjectFromFolder) requires the specification of the Parent Folder Id (CMIS folderId) parameter even though the CMIS standard defines it as optional. When you define the ECM server properties for an Alfresco Community server.Deviations from the CMIS standard . You can contact your Alfresco Community administrator for complete connection information. Parent topic:Integration considerations for ECM products 874 . see the Alfresco topic Alfresco CMIS.When a new version of a document is being created. Reference For information about the Alfresco implementation of the OASIS CMIS standard. Alfresco requires a new unique document name to be specified.. " You can contact your Microsoft SharePoint administrator for complete connection information. the default CMIS web service context path is "/_vti_bin/cmis/soap".Setup .Integration considerations for Microsoft SharePoint IBM® BPM supports ECM integration with Microsoft SharePoint 2010. Information about specifying the context path is found in the topic "Accessing the SharePoint CMIS provider from IBM BPM. See the topic "Accessing the SharePoint CMIS provider from IBM BPM" for information on how to establish the addressability of the CMIS web service for IBM BPM.Reference Setup Your Microsoft SharePoint installation may use a URL convention for the CMIS web service endpoint that is not expected by IBM BPM.CMIS capabilities . When you define the ECM server properties for a Microsoft SharePoint server.Deviations from the CMIS standard . Other integration considerations for Microsoft SharePoint are described in the following sections: . CMIS capabilities Microsoft SharePoint supports the optional CMIS capabilities that are described in the following table: CMIS Capability Microsoft SharePoint ACL manage AllVersionsSearchabl false e Changes ContentStreamUpdat ability GetDescendants GetFolderTree Join objectidsonly anytime Multifiling false PWCSearchable PWCUpdatable Query Renditions true true bothseparate none false true none BPM Considerations Not applicable A search will only be applied to the latest (major) version of a document Not applicable Not applicable Queries cannot include any JOIN clauses Documents can only reside in one folder 875 Not applicable . . Parent topic:Integration considerations for ECM products 876 .Accessing the SharePoint CMIS provider from IBM BPM In IBM Business Process Manager (BPM) 8. .Unfiling false Documents are always filed in a folder VersionSpecificFiling false Deviations from the CMIS standard Microsoft SharePoint deviates from the OASIS CMIS standard in the following ways: . The CMIS functionality is comprised of nine separate web service endpoints.When a document is being created. see the Microsoft topic Content Management Interoperability Services (CMIS) connector overview (SharePoint Server 2010).The IN and LIKE operators are not supported for WHERE clauses in queries. the content of the document must be provided.0. the Content Management Interoperability Services (CMIS) standard is used to provide integration with Enterprise Content Management (ECM) systems like Microsoft SharePoint. Reference For information about the Microsoft SharePoint implementation of the OASIS CMIS standard. About this task In IBM Process Designer. For example. port.Download URL Rewrite Module 2. the URL includes the specified host. and context path. a connection cannot be made because the web service address is not known: http://hostName:portNumber/_vti_bin/cmis/soap/RepositoryService To enable IBM BPM to accommodate the naming convention used in SharePoint. This approach enables IBM BPM to successfully connect to IBM FileNet Content Manager. the URL uses a naming convention that is similar to the following examples: http://hostName:portNumber/_vti_bin/cmis/soap/RepositoryService. When IBM BPM attempts to contact the SharePoint server using the following URL.svc/kerberos Note: The above Kerberos URL is intended to provide an example of the naming convention that is used with SharePoint CMIS web service URLs. Instead. a SharePoint CMIS web service URL does not follow the same naming convention because the URL is not appended with the service name.svc/basic To enable the URL Rewrite Module to rewrite incoming request URLs from IBM BPM. The URL Rewrite Module provides a rules-based mechanism to rewrite the incoming request URL from IBM BPM before it is processed by the web server. For example. It explains how to map to the URL syntax conventions that are used by IBM BPM. this help topic does not include any information about Kerberos authentication.Define the rewrite rules in IIS Manager . complete the steps in the following procedure. Procedure 877 . FileNet uses the following naming convention to expose the CMIS RepositoryService endpoint URL:http://hostName:portNumber/fncmis/RepositoryService However.Access the SharePoint CMIS Provider from IBM Process Designer To perform these tasks. The CMIS functionality is comprised of nine separate web service endpoints.0 for Internet Information Services (IIS) 7 is required. Microsoft URL Rewrite Module 2.svc/basic http://hostName:portNumber/_vti_bin/cmis/soap/RepositoryService. However. IBM Content Manager. the Content Management Interoperability Services (CMIS) standard is used to provide integration with Enterprise Content Management (ECM) systems like Microsoft SharePoint. port and context path of the ECM server and the service name is automatically appended to the URL. When the CMIS web service URL is created at runtime. the following tasks need to be completed: . and other ECM systems that require the web service URL to be appended with the service name. consider the following request URL from IBM BPM: http://hostName:portNumber/_vti_bin/cmis/soap/RepositoryService The URL Rewrite Module enables the URL to be rewritten in the SharePoint format that is shown in the following example: http://hostName:portNumber/_vti_bin/cmis/soap/RepositoryService.0.Accessing the SharePoint CMIS provider from IBM BPM In IBM Business Process Manager (BPM) 8.0 for Microsoft IIS 7 . ECM servers are configured in the Process App Settings editor or the Toolkit Settings editor by specifying the host. In the Actions section. In the Using drop-down list. F. In the Action type drop-down list. Also ensure that you specify the correct context path in the Context Path field. B. Define the rewrite rules in IIS Manager by completing the following steps: A. Parent topic:Integration considerations for Microsoft SharePoint 878 . I. Click Test Connection to ensure that a successful connection exists. In the Pattern field.0 for IIS 7 by completing the following steps: A.microsoft. specify the following pattern:^. On your desktop.microsoft. In the Condition input field. Access the SharePoint CMIS Provider from IBM Process Designer by completing the following steps: A. Open the Process App Settings editor and select the Servers tab. B. Select a connection. E. specify the following condition input:{R:1} 3. Select Ignore case. Select Append query string. C. In the Name area. download it from one of the following web pages and then install it using the instructions that are found at one of the following web pages: . Select Rule > Inbound rules > Blank rule.svc/basic 3. In the Server Details and Server Locations sections. click Apply to save the changes. Verify that you have IIS 7 installed.*)$ 4. Ensure that you specify Enterprise Content Management Server in the Type field. complete the following steps: 1. 3.aspx?id=5747 2.(x86) http://www. specify the following pattern:(. select Start > Administrative Tools > Internet Information Services (IIS) Manager. select Matches the Pattern. specify CMIS URL rewrite rule.*cmis/soap/(.com/enus/download/details. Download URL Rewrite Module 2.*).*) 5. H. 6. In the Conditions section. In the Pattern field.com/enus/download/details. If Microsoft URL Rewrite Module 2. complete the following steps: 1. On the right side of the page. Click Add. select Does Not Match the Pattern. complete the following steps: 1.svc(.aspx?id=7435 . 4. The Add Condition dialog box opens. In the Check if input string drop-down list. The default context path is:_vti_bin/cmis/soap C. specify a rewrite URL that is appropriate for your configuration. In the Requested URL drop-down list. Select Ignore case. 2. For example:{R:0}. In the Rewrite URL field. D.0 is not already installed in your IIS 7 installation.svc/kerberos {R:0}. 2. specify the appropriate server information for your SharePoint installation.1. In the Match URL section. 3.(x64) http://www. select Regular Expressions. Click OK. G. IIS Manager opens. select Rewrite. 2. Select IIS > URL Rewrite. B. 879 . 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. The visualization is displayed in a new web browser window. .Running and debugging processes with the Inspector The Inspector in IBM Process Designer is key to an iterative approach to process development. Select the required data variables or tag groups that you want to visualize on the left side in the browser window. individual developers can run processes and services on the Process Center Server or remote runtime Process Servers. Parent topic:Building process applications 880 .Testing and debugging process applications . Using the Inspector.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. It contains the web-based diagram view of the BPD. .Visualizing process data Use the data visualization option in IBM Process Designer to create a visual representation of a selected business process definition (BPD). output. variables are listed according to their attribute definition (as Inputs. Where an activity is mapped to more than one tag group. However in a tag group. you can map the local variables and apply tag groups to elements of a process. The icons for the input mappings are displayed on the left side of an activity in the visualization diagram and the output mappings are displayed on the right side. A process uses variables and business objects to contain the data that flows in and out of its activities. the labels that contain the tag group are stacked above each other in a tab.Visualizing process data Use the data visualization option in IBM® Process Designer to create a visual representation of a selected business process definition (BPD). You must refresh the browser to view the changes. The parent process and all its subprocesses can be displayed according to breadcrumb selections at the top in the browser window. For example. it is displayed as both input and output icons in the data visualization diagram. The activities in the selected BPD that use the same tag groups display same-color labels. or you can close the browser window and relaunch it. When you design a process in Process Designer. Prerequisite: To visualize process data. However. You can click a subprocess within a process in the data visualization diagram to visualize that subprocess. and you can create a visual representation of this data for a selected business process definition (BPD). a group of similar and related values can be grouped together under a single key. 881 . A tag group is a key-value pair that you can use to associate a service in a process. Tag groups are displayed as labels above the activities in the data visualization diagram. It contains the web-based diagram view of the BPD. The tag groups are applied to services within a process. under the selection area on the left side of the diagram. All the activities that are mapped to the tagged services are displayed with appropriate labels in the diagram. Select the required data variables or tag groups that you want to visualize on the left side in the browser window. When you click any colored icon. The visualization is displayed in a new web browser window. Variables are represented by colored icons in the data visualization diagram. the labels for all icons of the same color slide out and the actual variable names are displayed. The procedure for defining tag groups is similar to the procedure for defining regular tags. and private variables in a process can be defined as input or output mappings for an activity. Available. You can click the tab to display all the labels above an activity. and Retired can be created under the group Lifecycle Stage. Outputs. you must open the Process Designer desktop editor. During the design of a process. The activities in the selected BPD that have the same data variables are represented by icons that have the same color. Up to three input and output icons are visible on either side for each activity. the various stages in a software development lifecycle such as In development. the browser view does not detect those changes automatically. Note: If you redefine a process in Process Designer during visualization. input. or Private). Note: If a variable is mapped as both input and output for an activity. you can perform many of the available actions by using keyboard shortcuts.. . Parent topic:Testing and debugging process applications 882 . . or private variables used in a process.Visualize tag groups Select and visualize the tag groups defined for a process.Keyboard shortcuts for data visualization In the data visualization diagram in the web browser window.Visualize variables Select and visualize the local input. output. output. The activities in the selected BPD that have the same variables are represented by icons of the same color. Click any colored icon to slide and display the labels that contain the actual variable names for all same-color icons. The input and output variables are global to the process. 3.Visualize variables Select and visualize the local input. 5. Select Data from the drop-down list in the selection area on the left side in the browser window. Outputs. Use the zoom in or zoom out bar in the upper right corner to enlarge or reduce the diagram view in the browser window. output. or private variables used in a process. Procedure 1. Open a business process definition (BPD) in IBM® Process Designer. Private variables can be defined on the main process and the subprocesses inherit them. or Private and select the input. Parent topic:Visualizing process data Related information: Creating custom business objects in Process Designer Declaring and passing variables 883 . if you browse into a subprocess the same variables are displayed. Alternatively. 2. Up to three icons are displayed on either side of each activity.The data visualization diagram opens in a new web browser window. or private variables that you want to visualize on the activities in the diagram on the right side. However. private variables defined on a subprocess are visible only to that particular subprocess. Click the Data Visualization button in the upper right corner. Click a subprocess within a process in the diagram to visualize that subprocess. 6. Click the Minimize button on the left side to hide the variables list and view only the data visualization diagram. 4. click Inputs. Click the down arrow spinners below the third icon on either side to display the next three icons. Under Variable. click Playback > Visualize Process to view the data visualization diagram. Click the up arrow spinners on either side to view the earlier icons.Variables are displayed as colored icons in the diagram. 7. Under Tag Group Value. //@ServiceName "myService". Use the zoom in or zoom out bar in the upper right corner to enlarge or reduce the diagram size in the browser window. Click the tab of stacked labels in the diagram to display all the labels on top of the activity.Tag groups are represented by labels on top of the activities in the diagram. click Playback > Visualize Process to view the data visualization diagram. Open the Process Designer desktop editor. Click a subprocess within a process in the diagram to visualize that subprocess. Procedure 1. where myService is the exact name of the service. Where an activity is mapped to more than one tag group. an annotation that includes the service name must be added to the script activity.executeServiceByName() JavaScript function. The activities in the selected business process definition (BPD) that have the same tag groups display labels that have the same color. 6. Parent topic:Visualizing process data Related information: Tagging library items 884 . 7. the labels that contain the tag groups are displayed stacked on top of each other in a tab. Before you begin To perform this task. 5. If the process and its subprocesses use the tagged service. Tag groups are specific to the services within a process. For example. select the tag group and its values that you want to visualize in the diagram on the right side. you must be in the IBM® Process Designer desktop editor. Add the //@ServiceName annotation followed by the exact name of the service. Alternatively. Open a business process definition (BPD) in the Designer view. Select Tag Groups from the drop-down list in the selection area on the left side in the browser window. Click the Minimize button on the left side to hide the tag groups list and view only the data visualization diagram. 4. Note: A script activity can call a service synchronously from a BPD using the tw. Click the Data Visualization button in the upper right corner.The data visualization diagram opens in a new web browser window.system. To visualize the tag groups defined for such a service. 3. the tag groups are displayed for both. to the first line of the script activity.Visualize tag groups Select and visualize the tag groups defined for a process. 2. Press Tab again to access the process. and 3rd position on the left side of an activity r+u (r key press followed by u key Move up the up arrow spinner on the press) right side of an activity r+d (r key press followed by d key Move down the down arrow spinner on press) the right side of an activity r+1. 2. or 3 (r key press followed by 1. Table 1.Keyboard shortcuts for data visualization In the data visualization diagram in the web browser window. the navigation depends on the order in which the user added the nodes in IBM® Process Designer during the process design. Press Shift and Up arrow or Down arrow to scroll the diagram vertically. and 3rd position on the right side of an activity For tag groups: e Expand and display all the tag groups defined for an activity 885 . you can perform many of the available actions by using keyboard shortcuts. Instead. Press Shift and Right arrow or Left arrow to scroll the diagram horizontally. 4.Note: The navigation through the process nodes is not in the order in which they are displayed in the diagram. For process activity navigation Key combination Function For data variables: l+u (l key press followed by u key press) Move up the up arrow spinner on the left side of an activity l+d (l key press followed by d key press) Move down the down arrow spinner on the left side of an activity l+1. 3. Use the Right arrow key to zoom in the process and the Left arrow key to zoom out. 2nd. Expand or collapse the icon located at or 3 key press) the 1st. Once you select the required connection. or 3 (l key press followed by 1. Press Tab to access the zoom in or zoom out bar in the upper right corner. 2nd. 2. use the Right arrow and Left arrow keys to browse to the process nodes. or 3 key press) the 1st. Use the shortcut keys described in the following sections to browse through various areas in the data visualization diagram in the browser window. Then use the Right arrow and Left arrow keys to toggle the lane header and first process node in the lane. use the following shortcut keys to browse the data variables or tag groups visible for the activity in the diagram. Then use the Up arrow and Down arrow keys to toggle among the connections. Use the Up arrow and Down arrow keys to toggle the swim lanes in the process. Expand or collapse the icon located at 2. After you have selected a process activity. 2. To browse through the process diagram on the right side in the browser window: 1. 5. 2. Press Enter on OK or Cancel to submit or cancel your inputs. 3. and so on To browse through the selection area on the left side in the browser window: 1. Press Tab to browse through the list of check boxes available for the data variables or tag groups.Press Space to select or clear the check box. 3. 2 is the second one.Press Tab to toggle between the text boxes for tag group name and value. Press Tab to access the drop-down list for data variables and tag groups. and so on Select the tag group located at the 1st.e+1. 2. . 3. press Space to toggle the checked or cleared state. Parent topic:Visualizing process data 886 . OK. the Check if this is a Tag group check box. 2. Press Enter on any process entry in the list to visualize the diagram of that particular process. and Cancel. Use Tab or Shift+Tab to move up and down the list of check boxes. where 1 is the tag group placed directly above the activity. 2. Use the following shortcut keys to browse in New Tag or Tag Group in Process Designer: . Use the Up arrow key to select Data and the Down arrow key to select Tag Groups. To browse through the breadcrumb area at the top of the browser window: 1. . Inside each check box. Press Tab to access the first process in the breadcrumb area. Press Tab to browse forward in the list of processes and Shift+Tab to browse backwards. and 3rd position and so on. 2nd. you can view all previously run and currently running instances on the IBM Business Process Manager servers in your environment. See the following topics to learn more about using the Inspector interface. Using the Inspector. Prerequisite: To run and debug processes with the Inspector. A tree display of the process combined with indicators called tokens in the process diagram make it easy to understand where you are in the process. . . evaluating process execution step by step. Playback sessions help capture important information from different stakeholders in a process. The Inspector in IBM Process Designer includes several tools that enable you to complete tasks like the following in each of your configured environments: Table 1.Managing process instances Manage current and previously running instances of your process on the server that you select.xml) to control which users 887 . end users. and business analysts.Restricting access to debugging for services For services other than human services. you must be in the Process Designer desktop editor. Tasks for the Inspector tools Task Manage instances of processes Step through and debug a process Description When you run a process. for example.Running and debugging processes with the Inspector The Inspector in IBM® Process Designer is key to an iterative approach to process development. You can use the Inspector to demonstrate current process design and implementation in playback sessions. For a selected instance. see the currently running step and then move forward through the process. You also have the advantage of seeing the variables used in each step and their corresponding values (where applicable). Use the IBM Business Process Manager configuration file (99Local. Taking an iterative approach to process development ensures that your process applications meet the goals and needs of everyone involved. You can also manage previously run instances by filtering or deleting specific records. individual developers can run processes and services on the Process Center Server or remote runtime Process Servers. You can manage running instances by halting and then resuming them. you might need to limit access to debugging functionality in the Inspector in IBM Process Designer. such as management. and then make the necessary changes there. .Resolving errors Find the source of errors generated when running your business process definition (BPD) and resolve them. To edit the settings. Copy it to the 100Custom.xml file.have the ability to debug services. .Inspector reference Learn how to access and use each feature provided by the Inspector. . find the debug section in the 99Local.Stepping through a process Step through process execution to ensure that your BPD works as expected.xml file. . Parent topic:Testing and debugging process applications Related information: Restricting Inspector actions for online Process Servers 888 .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. The Inspector shows the running and completed instances on the Process Center Server for all snapshots (versions) of the current BPD. To learn how to connect to remote Process Servers. To control instances. If you click the Run icon while All versions is selected from the list of snapshots. Procedure 1. the Inspector runs the most recent snapshot of the BPD on the Process Center Server. if you want to stop an instance that you started earlier. Parent topic:Running and debugging processes with the Inspector 889 . the snapshots available are limited to the snapshots that are deployed on that server. Click the Run button in the upper right corner. When IBM Business Process Manager prompts you to change to the Inspector interface. click Yes. 5. Tip: You can also filter the list of instances shown by providing a name in the Instance Name field and using the Status drop-down menu. 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. 3. 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. Open a business process definition in IBM® Process Designer. For example. To run a process on a different server using the Inspector. For remote Process Servers.Managing process instances Manage current and previously running instances of your process on the server that you select.Note: Click the check box if you want IBM Process Designer to change interfaces without prompting for approval. 2. In the Process Instances tab. About this task Note: To learn more about the Inspector interface before you begin. you can see all currently active and completed process instances. see Inspector reference. select an instance from the list and then click the toolbar option that you want. To view instances running on a different server or to view instances for a different version of the BPD. click the instance and then click the Terminate Button to terminate the instance. 4.Important: Remote Process Servers must be connected to your Process Center to be available. select a different server or snapshot from the drop-down menus in the toolbar. when you attempt to debug a service in the Inspector in IBM Process Designer.xml file. by default. all users have access to debugging for services. find the debug section in the 99Local.Restricting access to debugging for services For services other than human services. So. . If set to false . Use the IBM Business Process Manager configuration file (99Local. By default. If you want to limit access to users who are members of the Debug group.xml file.xml file enable you to configure debugging functionality for services. IBM BPM simply runs the service without providing any debugging feedback. you might need to limit access to debugging functionality in the Inspector in IBM® Process Designer.xml) to control which users have the ability to debug services. The following elements in the debug section of the 99Local. this element is set to false . To edit the settings. Establishes whether IBM BPM users who do not belong to the Debug group (defined in the following setting) can access debugging functionality. which allows users who do not belong to the Debug group to access debugging functionality. set this element to true . and then make the necessary changes there. Remember: The access restrictions do not apply to human services. Copy it to the 100Custom. Element Default setting <enabled>true</enabled true > <enforce-debugrole>false</enforcedebug-role> false 890 Description Establishes whether debugging of services is enabled. Only one debug role can be defined. --> <enabled merge="replace">true</enabled> <!-. then this setting has no effect. --> <enforce-debug-role merge="replace">true</enforce-debug-role> <!-. If both of the preceding settings are true. If you do not specify any value for the debug role this will disable the debugging functions.Defines whether or not users that do not belong to the debug role can access debugging functions for services.<debugrole>debug</debugrole> Specifies the role membership that users must have in order to access debugging functionality. If this is false then debugging a service will simply run the service. If one or both of the preceding settings is false (enabled and enforcedebug-role).If you do not specify any value for debug-role .Indicates whether or not debugging of services is enabled. or is enforce-debug-role is false then this has no effect. debugging functionality is disabled.xml file is shown in the following example: <server merge="mergeChildren"> <debug merge="mergeChildren"> <!-. If enabled and debug-role is true.Specifies the role a user must be a member of to debug a service. then a user belonging to this role will have access to debugging functions.A user who does not belong to this role will not have access to debugging functionality. then: A user who belongs to this role will have access to debugging functionality. debug The debug section of the 99Local. If enabled is false. A user that does not belong to this role will not have access to debugging functions. Only one user role can be defined. --> <debug-role merge="replace">debug</debug-role> 891 . hence the service will run as it would normally. and the debugging functions will be turned off. </debug> </server> Parent topic:Running and debugging processes with the Inspector 892 . In the Process Instances tab. This is controlled by lane assignments and routing for activities. Click the Refresh icon in the toolbar. To learn how to connect to remote Process Servers. click Yes. the Inspector runs the most recent snapshot of the BPD on the Process Center Server. the snapshots available are limited to the snapshots that are deployed on that server. You can use this functionality for team playbacks and to help debug your process. 2. The Inspector shows the progress by moving the token to the next step in both the diagram and the navigation tree. When the task is complete. 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: 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. Optional: To view instances running on a different server or to view instances for a different version of the BPD. you might need to select a user account or provide a password for a specific user account in order to run a task. Click the Run button in the upper right corner. Open a business process definition in IBM® Process Designer.Stepping through a process Step through process execution to ensure that your BPD works as expected. click the new or received task and then click the Run button. select a different server or snapshot from the drop-down menus in the toolbar. 8. and linked processes as you step through their contents by double-clicking on the activity in the diagram 893 . 7. 6. you can step through the execution to ensure that your business process definition works as expected. Note: To learn more about the Inspector interface before you begin. For remote Process Servers. When IBM Business Process Manager prompts you to change to the Inspector interface. To run a process on a different server using the Inspector. you return to the Inspector. If you click the Run icon while All versions is selected from the list of snapshots. About this task When you run a process. You can expand subprocesses. In some cases.Note: Select the check box if you want IBM Process Designer to change interfaces without prompting for approval. Procedure 1. 3. See Assigning teams to BPDs and lanes and Assigning teams to BPD activities for more information. if the task generates a Coach. 4. enter requested values and complete the form. 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. event subprocesses. Complete the task when it runs.Important: Remote Process Servers must be connected to your Process Center to be available. For example. see Inspector reference. 5. The Inspector opens the Execution Evaluator tab and shows the values for the parameters within the selected variable. Even if you do not expand a subprocess activity. 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. The results are displayed in the bottom pane of the tab. 10. enter the JavaScript expression and click the Run icon at the top of the Evaluator. and then click the Run task icon. 11. Click the Refresh icon in the toolbar.view. In the Process Instances tab. 12. You can use the Execution Evaluator to inspect the variable values as they change through the flow of the business process definition. click the process node in the navigation tree. To see the variables passed from step to step. you still step through activities contained in the subprocess. Parent topic:Running and debugging processes with the Inspector 894 . 9. Right-click a variable and then click Show in Execution Evaluator. Note: You can also manipulate variables in the Execution Evaluator using JavaScript expressions to validate your process implementation. To do so. click the task for the next step. See Debugging client-side human services. 2. When IBM Business Process Manager prompts you to change to the Inspector perspective. click the new task. Open a business process definition (BPD) in IBM® Process Designer. The Inspector moves to the next step in the service flow. When prompted. To move to the next activity in the service flow. see Inspector reference. and then click Debug task. B. 4. You are logged in to the web browser using the selected user name.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. Click Run. For a different user. pausing on the first step after the Start event. Before running each step in the service flow. Depending on the task implementation. 3. You can use the information from the debugging process to help identify the point at which a process instance is not functioning as expected. Complete the following steps to debug the client-side human service: A. click Yes. examine the variable values that are displayed on the sidebar at each point to determine whether they are expected. C. the user name that you select must belong to a user group that has read access to the corresponding process application. You can choose to debug the service as the user that claimed the task or as a different user. As you step through an underlying process or service in the debug session in your browser. In the Process Instances tab. Use the actions on the sidebar to proceed with the debugging of the clientside human service. the Inspector interface shows the same progress in its diagram view and navigation tree. select the user that you want to debug the client-side human service as. complete the coach and trigger the boundary event to transition out of the coach. About this task The Inspector executes a debugging session in a browser window. the client-side human service Inspector opens in a browser window. Procedure 1. click Step Over . Note: To learn more about the Inspector interface before you begin.If the task that you are debugging is implemented as a client-side human service.Note: Select the check box if you want IBM Process Designer to change interfaces without prompting for approval. 895 . If this activity is a coach. D. E. complete the steps in one of the following procedures: . B. click Run to run all code and logic and then view the end values. the Inspector shows progress through the service. Parent topic:Running and debugging processes with the Inspector 896 . and then repeat the actions in step 4. complete the following steps to debug the service: A. go back to the BPD Inspector window and click Refresh to update the task status accordingly. the followed path is highlighted and a colorcoded token marks the current position in the service flow. To continue through the rest of your BPD. click the Process Instances tab in the Inspector. When the debugging of the client-side human service is complete.F. Complete the debugging of the client-side human service in the Inspector browser window. . If the service requires user input. using tokens in the diagram and navigation tree. On the clientside human service diagram. If the service does not require user input. H. At the same time. using tokens in the diagram and navigation tree. (Optional) To view the progress of the service execution. At the same time. 5. 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. G. In the debugger session in your browser. the Inspector opens the currently executing service in the Services in Debug tab and shows progress through the service. The Inspector moves to the next step in the process flow.If the task that you are debugging is not implemented as a client-side human service. you can click the Designer tab in the upper-left corner of the browser window. 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. The BPD Inspector opens a debugging session in a browser window. use the Step button and complete the fields for any associated coaches to step through each part of the service. such as stack trace details. including stack traces. About this task When you run a process or a service and an exception occurs in the instance.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. 3. 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. Click the error shown in the navigation tree to open the Runtime Error Information window. the Inspector clearly identifies the error in the diagram and navigation tree. 2.Resolving errors Find the source of errors generated when running your business process definition (BPD) and resolve them. the Inspector displays the error in the BPD diagram and also in the navigation tree.Tells you exactly where the error happened . Parent topic:Running and debugging processes with the Inspector 897 . 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. Click More in the Runtime Error Information window to show additional details about the error. The Inspector copies all information to the clipboard. When the execution of a BPD does not complete successfully. The Inspector also: . 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. (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. type employee in the Instance Name field and select Active from the Status dropdown menu. 898 . if you want to see only active process instances that include the word employee in their name. For example.Inspector reference Learn how to access and use each feature provided by the Inspector. which means any action you perform or any data shown in the other areas of the Inspector apply to this instance. or debug services. 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. in the preceding image. Use the icons in the toolbar to manage process instances. For more information. The Process Instances tab includes a Snapshot column so that you know which version of a process the currently displayed instances are running.3 4 5 Use the drop-down lists to choose a different server on which to run the current BPD. 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. You can also choose a different snapshot if you want to run a different version of the BPD. Remote Process Servers must be connected to your Process Center to be available. the current task is the first task in the BPD called Submit job requisition. Shows the current task for the selected process instance. 899 . For example. run tasks. you have to start the BPD again by choosing the run icon at the upper right of the BPD diagram. In the preceding example. 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. To run a process on a different server using the Inspector. To learn how to connect runtime process servers to the Process Center. the Snapshot column displays Tip to indicate that you are running the version of the process currently under development in the Designer. see Inspector toolbar options. Note: When you change servers or versions in the Inspector. The navigation tree continues to expand if you decide to run the task and step through the entire process in the Inspector. the red token above and the yellow halo around the Submit job requisition task indicate the active step. Table 2. Shows a navigation tree of the execution progress for the selected instance. In the preceding example. we can see that the requisition variable is used in the active step. In the preceding example. You can choose to show less information (Simple) or more (Edit & Debug).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. When you open the Inspector interface. you can see the first step in the instance (the start of the process) and you can see the active second step. Removes any record of the selected process instance. Use the drop-down menu to change the Inspector interface display. You can select a variable. Shows the variables used in the current step. right-click. 900 . Stops a running process instance. Resumes a suspended process instance. Toolbar icons available on the Process Instances tab Toolbar icon Function Pauses the selected process instance. If you want to view other information about the BPD for the selected instance. you see the Standard display which is described in the preceding rows. the following toolbar icons are available to help you manage those instances. and then select Show In Execution Evaluator to view and manipulate the variable values. Inspector toolbar options When viewing instances of processes in the Process Instances tab of the Inspector. indicated by the red token. you can click the other available tabs such as Overview and Variables. In the preceding example. Conditions are evaluated after the step has been completed but before the process enters the outgoing sequence flow. Runs the selected task. As you step through a service in the debug session in your browser. 901 .If a token is on a conditional sequence flow. For example. Opens the Details user interface for the selected process instance in Process Portal in your default web browser. 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. Understanding tokens In the Inspector interface. the process instance cannot proceed.If a token is on a step. a split can cause two tokens to be generated. the Inspector interface shows the same progress in the currently executing service in the diagram view and navigation tree. Pages through the BPD instances when more than 100 instances are displayed in the Process Instances tab.A process instance can generate several tokens. that step is in an active state. 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. The following general rules apply to tokens: . .Refreshes the current list of process instances based on the filter you have selected and the most recent data from the Process Server. You can test the interaction between the user interface and the process. Until the step has been completed. 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. A web browser opens to display coach(es). the target step is enabled-it can receive the token-because the condition on the sequence flow was met. When stepping through a process instance. Opens a debug session in your default web browser for the selected task. These tokens are merged into a single token when the process reaches a join gateway. you need to click Refresh after completing a step so that the diagram view and navigation tree properly display your progress. . Parent topic:Running and debugging processes with the Inspector 902 . you are prompted to log back in to the web browser. the playback window opens in the default browser window for Process Designer. The following actions occur: . . ensure that the different user belongs to a user group that has read or write access to that process application. 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. You can choose to run the task as the logged-in user or as a different user.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. you can encounter the described behavior when you perform either one of the following actions: . . Depending on what artifact you are working with. Parent topic:Testing and debugging process applications 903 . For example. 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.When you claim a task that is currently assigned to a team that you belong to.If you select a different user name. The logged-in user is selected by default. About this task When you start the playback session. . different actions can trigger this behavior.If a playback action is performed using a different user name. . .The task is run in a web browser and you are logged in to the web browser using the selected user name. .Right-click a human service or a heritage human service and select Playback > Run Service to launch the playback session. you are prompted to select the user name that you will run the task as.After the playback action is complete.Open a heritage human service in the Process Designer editor and click Run Service to test it in a playback session.Click Run to claim a business process definition (BPD) task instance. For more information about using translated IBM Business Process Manager components. are called "bidirectional" scripts. by using various techniques such as correcting invalid connection information or logging errors that are captured with log4J or java. for example during login. . where the general flow of text proceeds horizontally from right to left. globalization support is built in through appropriate design and implementation of systems.util. Although bidi text runs in both directions. the languages that use bidirectional scripts are called bidirectional languages. software.logging.util. where the general flow of text proceeds horizontally from right to left. and calendar support for Hebrew and Hijri.Enabling error logging in Process Designer You can configure IBM Process Designer to log errors by using log4J or java. . see Known issues for translated IBM BPM components. You can then examine the logs to troubleshoot problems with Process Designer. the right-to-left direction is the norm. but by association.Bidirectional support in IBM Business Process Manager Scripts such as Hijri and Hebrew. and procedures.Contextual support IBM BPM offers contextual bidi support for languages such as Arabic and Hebrew. Parent topic:Building process applications 904 . 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. The attribute "bidirectional" (bidi) is used for scripts.Globalization To ensure that applications can be used in multiple geographical locations and cultures.Troubleshooting Process Designer and Process Center connectivity Resolve problems starting Process Designer. .logging. . The attribute "bidirectional" (bidi) is used for scripts. Although bidi text runs in both directions.If the direction of the window is right to left.Within the same window. but can be used for other purposes. or implementation of a service. see Coaches toolkit: Date Time Picker stock control. Parent topic:Globalization 905 . Bidirectional support in IBM BPM includes the following features: .Bidirectional support in IBM Business Process Manager Scripts such as Hijri and Hebrew.Layout transformation in Process Designer . 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. are called "bidirectional" scripts. Typically. the default direction of entry fields is right to left. If you are using heritage coaches to build your user interface. . where the general flow of text proceeds horizontally from right to left. the right-to-left direction is the norm.Within a right-to-left window. but by association. If you are using coach views. Bidirectional text layout transformation can be applied to any string variable (either input or output) as part of the preprocessing. see Configuring a Hebrew or Islamic calendar.Islamic (Hijri) and Hebrew calendar support When you are creating user interfaces in IBM BPM. postprocessing. IBM BPM provides built-in bidirectional (bidi) layout options for designing processes. . but entry fields that are to receive English text or numeric input must be defined as having a left-to-right direction.Applying bidirectional text layout transformation IBM BPM provides bidirectional (bidi) text layout options for process applications. . you can choose an Islamic or Hebrew calendar. the languages that use bidirectional scripts are called bidirectional languages. its elements are logically ordered from right to left and from top to bottom. text and graphics can have different directions.Contextual typing . . postprocessing.visual contextual right-to-left In the following example.visual left-to-right . 3.LRTL . Parent topic:Bidirectional support in IBM Business Process Manager 906 . In the Implementation tab of the Properties view.visual contextual left-to-right .bidiTransformation(tw. a logical left-to-right string is transformed to LRTL logical right-to-left and the Boolean value isSymmetricSwapping is set to true: tw.VCRL . Typically. To perform a text layout transformation in a client-side human service.Var1.LCLR .VLTR . wire it to a coach that has an input variable and text control that is bound to the transformed string variable.local.The input BidiFormat and output BidiFormat can have the following values: . 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.LLTR .system. true) 5. 4. 2. "outputBidiFormat". or implementation of a service. add a server script to a service. From the palette.Note: This transformation can be performed from any server-side service.local.VCLR . then run the coach. from within your client-side human service flow.Var.logical left-to-right .logical right-to-left .visual right-to-left .local. In the Variables tab for the service. enter the script for calling the bidi engine to implement the transform.VRTL .Var = tw. add an input string variable for the string to be transformed. select the server script.bidiTransformation(tw. such as a heritage human service. symmetricSwapping) where tw.system. About this task Complete the following steps for bidi text layout transformation: Procedure 1.Var1 = tw."input_bidi_format". In the Diagram tab. "LRTL".Applying bidirectional text layout transformation IBM BPM provides bidirectional (bidi) text layout options for process applications. What to do next To test your service. but can be used for other purposes. include a call to a server-side service.Var1 is the string to be transformed.logical contextual right-to-left .LCRL .logical contextual left-to-right ."LLTR".local. Bidirectional text layout transformation can be applied to any string variable (either input or output) as part of the preprocessing.local. such as an integration service. For example:tw. 907 . . and that the text alignment is right. where the general flow of text proceeds horizontally from right to left. . .Contextual support for names of diagram elements ensures correct display of bidi text not only in properties but also in diagram.Contextual support IBM® BPM offers contextual bidi support for languages such as Arabic and Hebrew. Contextual support ensures that when a first typed character is Hebrew or Arabic. Parent topic:Globalization 908 .Contextual typing is supported in descriptions in Process Center. contextual typing of the activity name is possible inside the BPD diagram. The following is a list of the different kinds of contextual support that IBM BPM provides. . control orientation and typing direction are right-to-left.When a new activity is dragged from the palette and dropped onto the business process definition (BPD) canvas.Contextual support in notes ensures right-to-left text direction of text inside the notes. If your administrator upgraded Process Center. Ensure that the URL prefix (http://hostname:port) is the same as the Process Center URL prefix. .ini file and locate -Dcom. This area of the Designer interface displays status conditions. check the lower right corner of the Process Designer.Confirm that you are using the correct user name and password. The default port is 9080. contact your IBM BPM administrator. you must log in using your IBM® BPM user name and password.Check the eclipse. . for example C:\IBM\ProcessDesigner\v8. 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. 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.logging. When you log in. Open the eclipse. If you do not already have a user account. 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. by using various techniques such as correcting invalid connection information or logging errors that are captured with log4J or java.url. . for example during login. you need to upgrade Process Designer to the same version by accessing Process Center from a browser and downloading Process Designer. 2. try one of the following tasks: .Troubleshooting Process Designer and Process Center connectivity Resolve problems starting Process Designer.processcenter.5.util.If the two versions are different. 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.Table 1.bpm.Confirm that Process Center is running by accessing it through a browser using the URL in the form http://hostname:port/ProcessCenter. 909 .Confirm that your Process Designer version matches the Process Center version.ibm. you are connected to the Process Center designated during installation of Process Designer.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. To determine your connection status. Process Designer communicates with Process Center using the following ports.Examine the IBM Business Process Manager logs for errors or information.Enabling error logging in Process Designer You can configure IBM Process Designer to log errors by using log4J or java. Refer to Port number settings in the WebSphere Application Server information center. ..logging .If you see a blank white Process Designer view or the view does not display fully. See Enabling log4J debug tracing . Parent topic:Globalization Parent topic:Building process applications 910 . .util.Use java.Table 2. enable a security option as described in Process Designer window is blank. See Enabling java.logging. 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. .Turn on Log4J debug level tracing. check that communication on the following ports is enabled. If you have a firewall or proxy server.util. If the display continues to be blank. press F5 to refresh. You can then examine the logs to troubleshoot problems with Process Designer. See IBM Business Process Manager log files. or are running a service that forwards the ports. or if you see an HTTP error.util.logging to write errors to a log. 2. The log4j. If you need to contact IBM Support.xml by adding this line:Dlog4j. Enabling log4J debug tracing Configure Process Designer to add debug statements to the ae.jar. extract the file log4j. Other logs are located in the <ProcessDesignerInstallationDirectory>\workspace\metadata directory.log in the main directory where Process Designer is installed. change the level value for the com.logging messages. From twappserver.jar in the directory <ProcessDesignerInstallationDirectory>\teamworks\eclipse\plugins\teamworks.appserver.xml.logging.util.lombardisoftware logger from error to debug.util. Close Process Designer.websphere_version\lib 3. You can find ae.util. You can then examine the logs to troubleshoot problems with Process Designer.xml file should be changed from: <logger name="com. Close IBM Process Designer.xml 6.configuration=file:<ProcessDesignerInstallationDirectory>/log4j. Restart Process Designer. Enabling java.xml to the root Process Designer installation directory. submit these logs to get the problem resolved faster. You can use the information in these logs to troubleshoot a problem. Locate the file twappserver. In log4j.lombardisoftware" additivity="false"> <level value="error" /> <appender-ref ref="TWConsoleAppender" /> <appender-ref ref="TWFileAppender" /> </logger> to: <logger name="com.ini and point to the updated log4j. and note down the time stamp. 4. recreate the problem. Traces and logs Error logs and traces can be located in a number of different places within the Process Designer installation directory. Open eclipse.log file should now contain the debug and error messages from Process Designer. follow these steps: 1.log file: 1.lombardisoftware" additivity="false"> <level value="debug" /> <appender-ref ref="TWConsoleAppender" /> <appender-ref ref="TWFileAppender" /> </logger> </p> 5.Enabling error logging in Process Designer You can configure IBM® Process Designer to log errors by using log4J or java. The ae. 911 .logging To enable logging for all java. ini and add this line:-Djava. Open eclipse. Parent topic:Globalization Parent topic:Troubleshooting Process Designer and Process Center connectivity 912 .logging.Level=ALL 4.2. recreate the problem and examine the logs for errors.util. Navigate to the main Process Designer installation directory 3. Restart Process Designer. context.IBM BPM REST server such as "/rest/bpm/wle"teamworks (String). Generally.IBM Process Portal server such as "/ProcessPortal" context.context. Views that are defined in the layout are children of this root element.binding){ var title = this.context. IBM BPM Teamworks server such as "/teamworks"processPortal (String). The view must not delete this DOM element. Use this root DOM element to scope your search. To access the data. Use this API to construct the URL that your coach views use to connect to these servers. Provides access to the configuration options of the view.contextRootMap Contains the values of different context roots of the IBM® BPM servers.get("value") Where value is a special property name that returns the bound data object. use the following call:this.phoneBook.binding.element context. The object has the following properties:rest (String). 913 . These configuration options include the properties that users can set for the view such as the label for a button control and metadata properties. if a view is bound to local.For example.options Contains the root DOM element of the coach view. you can access its properties.binding Description Provides access to the data object that is bound to the current view. Properties Through the context object.title. Property context. the view uses this root DOM element to locate its own content.The context object The context object provides access to helper functions. the view can get the title by using the following code:if (!! this.Note: Multiple instances of the same view can be on the same HTML page.get("value") } context. such as a callback to fire a named boundary event.binding. enablingDocumentId (String). The ID of the user.snapshotId (String). The ID of the process or toolkit that contains the coach definition.user_loginName (String). The language of the user. The ID of the process or toolkit snapshot that contains the coach definition. The locale of the user. The text direction preference of the user. 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. The name that the user used to log in. Generally context.paShortName (String).instanceId (String). The ID of the document that activated the case activity whose implementation the current human service belongs to. The ID of the case folder if the current human service is running in the context of a case instance. 914 .context.system Returns an object with the div ID of the subview as a property name. otherwise the returned value is an empty string.user_localeLanguage (String).user_id (String). see Example: Get and use a domNode and Example: Get a div ID. The full name of the user.paId (String).subview[viewid] context. An empty string is returned if the triggering activity was not activated by a document or is not a case activity.getSubview() is a more convenient function to use. For more information.taskId (String). The ID of the current task or process in which the coach is running. The acronym of the process or toolkit that contains the coach definition. otherwise the returned value is an empty string. The instance ID of the BPD in which the coach is running.startingDocumentId (String).user_fullName (String). there is usually only one property. In a nonrepeating scenario.caseFolderId(String).bpm. The view ID or control ID. Provides access to the following system values:baseTextDirection (String) .user_localeCountry (String).viewid (String). settings Provides access to the following properties related to timer-based refreshing for coach views: TimerCoachViewEnabled (Boolean). The unique identifier of the team.team. The list ("[]") is empty by default. Administrators can override the settings specified in the models using this property. Each item in the list for context.team.bpm. Contains the unique identifier for this view definition. requiredOrder). The value is defined in seconds.member context. This setting defines the minimum time between refresh requests handled by the instance user interface coach controls. The unique identifier of the team. This setting specifies the frequency of refresh requests triggered by the timer coach control.manager context. 915 .member is an object that contains the following properties: name (String).TimerCoachViewRefreshInterva l (Integer).system.team. The default value is 10. The list ("[]") is empty by default.getSubview(viewId.bpm.bpm. which means that refresh calls to the server are only sent if at least 10 seconds have passed since the last refresh call. see context. indicating that the value used in the coach control configuration is to be used. By default.bpm.manager is an object that contains the following properties: name (String). For more information. this setting is true.team. Lists the teams that the current user is manager of.MinimumCoachViewRefreshInt erval (Integer). The name of the teamid (String). The value is defined in seconds. which means the timer control is active. The name of the teamid (String).context. The default value is1. context.bpm.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. Each item in the list for context. Lists the teams that the current user is member of. Multiple view instances might have the same viewId. you can access its functions. do not call this API between deleting a domNode of the content box and the rendering of the first repeating element.cancelBoundaryEvents() context. for example. Important: If the coach view that contains a view-managed content box is bound to a list that is not empty.currentItem) The framework displays a message at run time when there is a mismatch in list lengths. see Data binding for coach views.This contained coach view is bound to the currentItem of a different list.containDiffLoopingContext() Description Returns the type of the data binding. For example.trigger(callback) function.Important: Do not use this API to send sensitive or confidential information. An object that has a name property. 916 . Cancels the boundary events that have not been sent to server.Functions Through the context object.bindingType() context. For more information. see the context. You use containDiffLoopingContext() to. 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. 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. the message occurs for the previous example if ListA has four items and ListB has three items. For more information. 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. The return value might not be accurate.broadcastMessage(message) context. message(Object). Broadcasts the supplied message.For example. Function context. the API returns a value of true for the following structure:TableView (bind to ListA[]) ContentBox TextView (bind to ListB. The view instance of the parent view. Indicates the position so that data binding and configuration indexes can be adjusted or zero-indexed. see Example: Get and use a domNode. The HTML DOM element of the content box or node of any coach view. the parent view can be computed based on the document order. 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.rowTemplate. parentView) Creates a coach view instance and any subview instances under the specified DOM element. Deletes the coach view instance and any subview instances. The HTML DOM element of content box or the node of any coach view. var viewArray = this.context.cloneNode(true). location). see Example: Get and use a domNode.parentNode. var trElement = document.var location = 5. context. which is usually a content box div. The framework then returns an array of these view instances.getElementById("myId").The following code snippet shows how to delete a view instance:var nodeToDelete = document.removeChild(nodeToDelete). If domNode is the node of any view other than a content box.createView(oneDiv.appendChild(oneDiv).context.deleteView(domNode) For more information.tableElement. The following code snippet shows how to create a content box view. var oneDiv = this. this.domNode(Element). If (domNode is the node of a context box. trElement. the framework creates a single instance of the view and returns it.createElement("tr").deleteView(nodeToDelete). 917 .index(Integer) (optional). this. For more information. // rowTemplate is the contentBox that contains some nodes // the view nodes define table columns. starting from the specified DOM element. index. nodeToDelete. parentView(CoachView) (optional).appendChild(trElement).context.createView(domNode. alternatively. domNode(Element). context. The options are returned even when the view represented by viewDomNode is not yet constructed. Typically.context. The search starts with the parent DOM node of the this. 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.get("value"). null is returned.set("value". the function returns EDITABLE.getDomNode(uniqueViewId. viewDomNode(Element).startNode and the search checks only the immediate children of the start node unless you pass in optParam. Parameters that modify the scope of the search.deepSearch=true._metadata.uniqueViewI D(String). Returns a String containing the value of the visibility setting of the ancestors of the coach view that is calling this function. The HTML DOM element of the child view.element unless you pass in a different start node by using optParam. If a given property is not specified for any screen size.getStyle() Returns the currently applied positioning information specified in the Positioning properties of the coach designer.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._metadata.getOptions(childViewDomNode). context.optParam(Object) (optional). The following properties are defined: width(String) height (String) min-width (String)minheight (String)margin (String)padding (String)overflow (String) 918 .context. The value to search for in the data-ibmbpm_uniqueViewId of the domNode. If visibility values of all of its ancestors are set to DEFAULT.label. "READONLY"). 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.The following code snippet is an example of how you could use this API: var childOptions = this. Returns the options object for the coach view given its viewDomNode. var childLabel = childOptions. childOptions.visibility.getInheritedVisibility() context. optParam) context. A value of true enables the group notification. only thestyle type is supported.bind(type. Only one notification or callback is triggered even if more than one positioning property is changed.getStyle() method to get the currently applied positioning. The function to be invoked as a callback. Currently. If it is not specified then no scope is defined. callbackFunc(Function). The returned object contains a unbind() method that takes no parameter. all previous callbacks will be removed. 919 . (Optional) Indicates the "this" to be used when invoking the callback function. callback (function). scopeObject) context.Normally. This function returns an object that can be used to unregister the callback. callbackFunc. The event object that is passed into the callback contains a single property type of value groupNotification. Coach views should retrieve the latest binding and configuration option values after receiving the group notification. A value of false disables the group notification.context. Any other values will cause an exception to be thrown. the callback function invokes the context. The following parameters are defined: enable(boolean). Specifies the callback to call when group notification is enabled. scope(Object) The function scope when the callback is invoked. This setting change can be a design-time change in the positioning settings or a change in the run-time screen size. For now. It does not have any information about the individual changes.setGroupNotification() Registers a callback function to receive a change notification associated with the specified type. the only supported value is style. 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. This function has no type parameter. When enabled. type(String). When enable is set to set to false.scopeObject(Object) . context. and port of the coach or a site listed on the white list.com. true) is that this. The escaped text is returned. Returns true if origin matches the protocol.origin as the parameter. https://bpm2. true) returns an array of subview context. a coach view receives a postMessage event.context. text(String). The text to escape. The default value is false. see Accessing a child coach view by using a control ID. viewId(String).mycompany. 920 .com:9443.mycompany.context. The call this. and http://bpm3.getSubview("viewid". The only difference between the two calls and the function call this. requiredOrder) Returns the subview instance given the subview ID. host.getSubview(viewId. false) returns the same array.getSubview("viewid".isTrustedSite(origin) objects whose order matches the order of the DOM nodes in the DOM tree.com:9080. For more information.origin(String). The call this. For example. The view ID or control ID of the subviewrequiredOrder(boolean) (optional). This function is used to avoid potential cross-site scripting (XSS) attacks. The coach view can check the origin of the event by calling this API using event.subview[viewid] except that the return value is an array of subview instances.context. Indicates whether the array that is returned must maintain the same order as in the DOM tree.mycompany. The protocol and host of the URL. Escapes the specified text.getSubview("viewid") returns an unsorted array of subview objects.context. This method is similar to context.htmlEscape(text) context. 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.getSubview("viewid". context. One reason it is not initialized is that load() of the parent view is called after the current load() function. isVisible(Boolean). the value false hides the domNodedomNode(Element) (optional). Because the parentview object is not fully initialized. context. The ID to be set. Shows or hides the specified DOM domNode) element by removing or adding a CSS class that sets display:hidden. As a result.parentView() 921 . If not specified. see Example: Get and use a domNode. the parentview object is created but not fully initialized.refreshView() Forces the coach view and all its subviews to rebind. context.element. which causes the view (and all its subviews) to refresh.Returns the parent view instance or null if there is no parent view. The value true shows the domNode. context. the change() callback is called.uniqueViewId( String). targetNode) ibmbpm_uniqueViewId property of the targetNode. the root element of the current view is used.targetNode(Element) (optional).setUniqueViewId(uniqueViewId Sets the uniqueViewId in the data. If not specified. The value true shows the domNode. When the domNode is hidden. the value false hides the domNodedomNode(DOMElement) (optional). isDisplay(Boolean). this function sets the property for the DOM node of the this. Shows or hides the specified DOM domNode) element by removing or adding a CSS class that sets display:none. the root HTML DOM element of the current view is used. For more information. context.context. During the invocation of load(). the parent coach or coach view reserves the space that domNode would occupy.setDisplay(isDisplay. If the call does not include the targetNode. the parent coach or coach view does not reserve the space that domNode would occupy. When the domNode is hidden. avoid calling this function in the load() function. The HTML DOM element that contains the data-ibmbpm_uniqueViewId property to be set.setVisibility(isVisible. The ) custom message is sent to the browser of a collaborating user.subscribeValidation() context.unsubscribeValidation() Unregisters the Coach View so that it no longer receives errors in the errors_subscription list. the coach framework calls the callback function when the boundary event is handled depending on the supplied options parameter. Views that do not have a data binding. The object that contains the custom message contents. If the property is set to true.type = "custom".The options parameter exists but does not contain the callBackForAll property. The callback function has a response object as a single parameter: {status: boundaryEventStatus}. context. context. callback(function) (optional)If a callback function is supplied. payload(Object). Example: Get and use a domNode 922 . The options parameter exists and it contains the callBackForAll property but the property is set to false.context. the callback is only invoked when the boundary event was successfully run (executed):The options parameter does not exist. These errors are contained in the errors_subscription list of the error event object. If any of the following conditions apply. The corresponding view on the collaborating browser receives the collaboration() callback with event. the callback is invoked regardless of the status of the boundary event.triggerCollaboration(payload Fires a custom collaboration event.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. can use this API to receive validation errors. The view still receives the errors list if it exists. such as the Tab stock control. Fires a named boundary event. The boundaryEventStatus parameter has one of the following values: options(Object) (optional)This parameter has a single property: callBackForAll (Boolean). context.context.id. Parent topic:The view object (this) 923 .id To get the ID of a subview. In this example. // This gives you the ID of the subview .getSubview("subviewID". 2 var subviewDomNode = subview.id. The following code example shows how to get a domNode and use it in a function.context. . the intent is to get the sixth element in the index of arrays. .Many functions of the context object take a document node (domNode) as an argument. 3 var subViewDomId = subviewDomNode. The parameter true ensures that the objects of the array are returned in the same order as the DOM. The parameter true ensures that the objects of the array are returned in the same order as the DOM.element. . 3 this. Example: Get a div ID To get the div ID of an element. "true")[5].element.1 The parameter subviewID is the control ID of the subview and corresponds to the value for the property data-viewid of the <div></<div> tag of the subview instance. 2 var subviewDomNode = subview.context. . The function getSubview(subViewID) returns an array of subviews.getSubview("subviewID".context. we want the sixth element in the index of arrays.2 Get the domNode of the subview element that is returned in step 1. The function getSubview(subViewID) returns an array of subviews. "true")[5]. In our example.2 Get the domNode of the subview element that is returned in step 1.3 Delete the subview by using the domNode that step 2 returns. . 1 var subview = this. 1 var subview = this.deleteView(subviewDomNode).element.context.3 Get the ID of the subview. use the syntax this. first get the domNode of the subview and then use .1 The parameter subviewID is the control ID of the subview and corresponds to the value for the property data-viewid of the <div></<div> tag of the subview instance.