Accessing Database Connection Management

Accessing Database Connection Manager

You can access the Database Connection Manager via the Configuration Management menu.

To access the database connection manager window

  • Click the Configuration Management menu and select Manage Database Connections.
    The Manage Database Connections window appears.


Adding Database Connections

If the database connection string you need does not exist, you can define a new one. There is no limit on the number of database connection strings you can define.

To add a database connection

  1. Open the Database Connection Manager and click the Create New Database Connection button [image].
    A Database Connection window appears.

  2. Enter a descriptive name for the database connection in the Name field.

    Note:
    The name you enter here is the name you will see in the Database Activities.

  3. Enter a description of the database in the Description field.

  4. Click the SQL syntax style drop-down list and select the type of database you will connect to. Your selection here determines the characters that begin and end SQL statements you send to the database.

  5. Click the Edit button next to the Connection String field.
    The Data Link Properties window appears.

  6. Select the type of OLE database to which you are going to connect, then click Next.
    The Connection tab appears.

  7. Enter the connection information required for steps 1, 2, and 3.

  8. Click the Test Connection button to test the database connection.
    A window confirms that the connection is working, or that it was unable to connect. If it was unable to connect, double check the connection information you entered.

  9. Click OK.
    The Data Link Properties window closes and the database connection string appears in the Connection String field.

  10. Click OK.
    The database connection information is saved. You can now use this database connection with BPM Suite.

Related Topics


Database Connections for Process Designers

About Database Connections

In order to create a database connection, you will need technical information about the database, including:

  • The OLE DB provider

  • The name of the server

  • A User name and Password for the server

  • The name of the database

In most cases, you will need information from an IT resource in order to create a database connection. If so, contact your system administrator. However, if you already know the information required to create this connection, please view the help topic Using Database Connection Management.


Removing Database Connections

If a database connection string will no longer be used, then you can remove it.

To remove a database connection

  1. Open the Database Connection Manager and select the database connection that you want to remove from the Connection Profiles list.

  2. Click the Remove button [image].
    A window confirms the deletion.

  3. Click Yes.
    The database connection is removed.


Using Database Connection Management

You can use the Database Connection Manager to name and define database connection strings in one location. This prevents you from needing to define a database connection in each Database Activity.

Managing Database Connections

  • Accessing Database Connection Manager

  • Adding Database Connections

  • Removing Database Connections


Bluespring BPM Console

BPM Suite Server Administration

Some features of BPM Suite are controlled through the Bluespring BPM Console. BPM Console is installed on the server that hosts BPM Engine. This application is ordinarily not necessary to design, configure, test, and manage processes. However, many non-standard configurations of BPM Suite require you to use BPM Console.

The following administrative activities involve configuration outside of BPM Designer, and may also involve Bluespring BPM Console:

  • Managing Custom Activities

  • Managing Servers

  • Setting Up LDAP Authentication

  • Configuring the SQL Reporting Server URL

  • Moving the Database to a New Server

  • Mapping BPM Suite Roles to Active Directory Groups

In general, this Help system will not provide information on how to perform these administration functions. Instead, it will refer you to the BPM Suite Operations Guide. This document should be available through the Bluespring Solution Center, on the Bluespring Partner FTP site, or by contacting Bluespring directly.

Related Topics

About Administrator Setup


Managing Custom Activities

BPM Suite comes with activities that cover a broad range of business functions. However, you may find it useful to create your own activity to accomplish some specific task. BPM Suite allows you to develop custom activities and use them within BPM Designer, similar to a plugin.

For information on registering your custom activity with BPM Designer and BPM Engine, please refer to the BPM Suite Operations Guide.

If you want to develop your own custom activity, you may also want to review the Bluespring Web Services SDK.

Related Topics

Bluespring Site Manager and BPM Console


Managing Servers

Most small-scale implementations of BPM Suite use only one server to host every Web service. However, in large-scale implementations, it may be beneficial to use more than one server. BPM Console is an application that allows you to organize, start, and stop BPM Engine on one or more server. You can also start and stop individual activities on a BPM server.

For information on managing BPM servers, please refer to the BPM Suite Operations Guide.

Related Topics

Bluespring Site Manager and BPM Console


Mapping BPM Suite Roles to Active Directory Groups

Using Active Directory with BPM Suite

You can configure BPM Web to use Lightweight Directory Access Protocol (LDAP) authentication with Active Directory. Technically, that means BPM Web will verify user names and passwords against Active Directory, rather than the database that comes with BPM Suite. Practically, this means that Users within your corporate domain will be logged into BPM Web automatically, eliminating the sign in step.

The steps described in this Help topic are the final part of a procedure that is described in the BPM Suite Operations Guide. Before you follow the steps in this Help topic, you must:

  1. Modify the db.xml file on the server hosting BPM Engine.

  2. Configure IIS authentication for BPM Web.

  3. Modify the web.config file on the server hosting BPM Web.

If you have not yet performed those steps, please refer to the BPM Suite Operations Guide to get started. Continue reading this Help topic after you have completed the first three steps.

This final step allows you to map BPM Roles to Active Directory Groups. Roles/Groups determine the permissions available to Users when they log in. If a User does not belong to any Roles/Groups, then he will not be able to log in to BPM Web.

Important:

To properly complete the mapping, you will need a working knowledge of Active Directory. You will also need to answer the following questions:

  • To which domain will users be bound, and is there a specific domain controller that you will target?

  • Is the domain controller configured to use the default port, port 389, or a different port, like the Secure Sockets Layer (SSL) connection port?

  • Should authentication be limited to users from a specific Active Directory sub-tree? If so, what is the path specification of that sub-tree?

    Example:
    OU=Bluespring Users,DC=bluespringsoftware,DC=com

  • Which Active Directory groups should be mapped to Bluespring roles?

  • Which Active Directory properties, if any, should be automatically transferred from the user’s Active Directory entry to their Bluespring role?

Updating the Sys_ActiveDirectoryUserClass lookup table

  1. Open the List Management window.

  2. Open the Sys_ActiveDirectoryUserClass list.
    The List Management (Sys_ActiveDirectoryUserClass) window opens with three columns displayed:

    UserclassGuid     - A string of letters and numbers that uniquely identifies each Role
    UserClassName     - The name of each Role
    ADGroup     - The binding information that associates each Role with an Active Directory Group

    Important:
    Do not use this list to add new Roles. Use Access Management to add a new Role.

  3. Click the ID button to hide the UserclassGuid column. You will not use it for this task.

  4. Each Role in the UserClassName column corresponds to a field in the ADGroup ("Active Directory Group") column. In the corresponding field, enter the following Object Attribute binding information for each Naming Attribute using "Little Endian" form:

    Naming Attribute

    Object Attribute

    CN

    Common Name; used to store the name of a user, computer, or container.

    Example:
    CN=Joe Smith

    Note:
    Since you are mapping BPM Suite roles to Active Directory Groups, you will not include a Common Name attribute in the mapping string. However, you can map a single CN to a role if necessary.

    OU

    Organizational Unit; stores the role associated with this profile.

    Example:
    OU=Sales
    OU=Technician

    Note:
    You can enter multiple Organizational Units for a single ADGroup. Separate each unit with a comma.

    Important:
    Must be the distinguishedName property for the Active Directory Group.

    DC

    Domain Controller; stores your corporate domain information.

    Note:
    Each component of the domain that is separated by a dot (.) needs its own DC attribute.

    Example:
    BluespringSoftware.com needs the following two DC attributes:

    DC=BluespringSoftware
    DC=com

    Example group mapping string:
    OU=Sales,DC=bluespringsoftware,DC=com

    Note:
    You do not need to enter "LDAP://" to the beginning.

  5. Click the Save Table button after you enter the necessary information.
    Users will now be automatically logged in to BPM Web using the same user name and password they use to access their computer while on your corporate domain.

  6. Close the List Management windows.


Moving the Database to a New Server

You may need to move the BPM Suite database to a different server. For example, if you increase your use of BPM Suite, you may want to purchase an upgraded server to handle the additional workload. The BPM Suite Operations Guide assumes that you know how to transfer the database to a new computer. The steps provided in the guide describe how to modify BPM Suite configuration files so that they recognize the new location of the database.

For more information on moving the database to a new server, please refer to the BPM Suite Operations Guide.

Related Topics

Bluespring Site Manager and BPM Console


Setting Up LDAP Authentication

You can configure BPM Web to use Lightweight Directory Access Protocol (LDAP) authentication with Active Directory. This process requires four steps:

  1. Modify a db.xml file

  2. Configure IIS

  3. Modify a web.config file

  4. Modify a list in BPM Designer.

For more information on completing the first three steps, please refer to the BPM Suite Operations Guide to get started. For more information on the fourth step, refer to the Mapping BPM Suite Roles to Active Directory Groups topic.


Adding User Functions

In addition to creating users and roles, you can also create User Functions, which act as a collection of security settings that control role permissions. You will first create a User Function and then select the Tool Bars to disable when a role is associated with this User Function.

To add a User Function

  1. Open the Access Management window and click the User Function button on the upper toolbar.
    The list of User Functions appears in the upper left pane.

  2. Click the Add button [image].
    Properties for a New User Function appear in the upper right pane.

  3. In the upper right pane, under Properties, click the Description row.

  4. Type a description of your new User Function.

  5. In the Name row, enter the name of the new User Function.

    Example:
    If you name a User Function HideConfigurationManagement, then other users can safely assume the User Function is used to hide the Configuration Management tab and menu.

  6. Select False from the System drop-down box.

  7. Depending on the category for which you want your Role to appear, in the Type drop-down list, select either General or Reporting.

    Note:
    A General User Function is anything that does not deal with the reporting feature in BPM Web, known as BPM Dashboard.

  8. In the lower left pane, define the tool bar permission for the UserFunction.

  9. From the File menu, click Save.
    This User Function is ready to be used by a Role.


Adding User Functions to Roles

Roles must be linked to one or more User Functions, which determine the permissions for all Users in that Role.

To add a UserFunction to a Role

  1. Open the Access Management window and click the Role button on the upper toolbar.
    The list of Roles appears in the upper left pane.

  2. Click the User Function button on the lower toolbar.
    The list of User Functions appears in the lower left pane.

  3. Select the Role to which you want to assign a User Function.
    A list of User Functions associated with the Role you selected appears in the lower-left pane.

  4. Select the User Function(s) you want to add to the Role you selected in step 3.

  5. Click File > Save.
    The User Function has been assigned to the Role.


Creating a User Function Type

By default, you can organize user functions by two types: General and Reporting. To help you organize your user functions, however, you can create additional user function types.

To create a user function type:

  1. Open the List Management window and double-click the list named Sys_UserFunctionType.
    The List Management window for Sys_UserFunctionType appears.

  2. Enter a name for user function type in the last row of the TypeName column.

  3. Press the Enter key.
    <New Item>     appears in the UserFunctionType column in the row in which you just entered a value.

  4. Optional: Enter a type description under the TypeDesc field and press the Enter key.

  5. Click the Save Table button.
    A window confirms the save.

  6. Click OK.
    List Management automatically assigns the list item an ID number under the UserFunctionType column.

You can now group user functions by this user function type in Access Management.


Editing User Function Properties

After you create a User Function, you can edit its properties.

To edit a User Function's properties

  1. Open the Access Management window and click the User Function button on the upper toolbar.
    The list of User Functions appears in the upper left pane.

  2. Select the User Function you want to edit.
    The User Function's properties appear in the upper right pane.

  3. Edit any of the following information in the upper right pane:

    For the

    Do the following

    Description

    Enter a description of the User Function.

    Name

    Enter the name of the User Function.

    System

    Select True if you want to protect this User Function from being deleted by non-administrators. Otherwise, select False from the drop-down list.

    Type

    Click the Type drop-down list and select either General or Reporting (or any other relevant category, if you have added others).

  4. Click the ToolBar button on the lower toolbar to see the ToolBar functions.

  5. Select any ToolBar function and click either Set No Access or Set Visible to make that ToolBar function a part of the selected User Function.

  6. Click File > Save.
    A window confirms the save

  7. Click OK.


Removing User Functions

If you no longer plan to use a User Function, you can remove that User Function.

Important:
After removing a User Function, it will no longer be available to any Role.

To remove a User Function

  1. Open the Access Management window and click the User Function button on the upper toolbar.
    The list of User Functions appear in the upper left pane.

  2. Select the User Function you want to remove.

  3. Click the Remove button.
    A window asks you to confirm the removal.

  4. Click Yes.
    The User Function is been removed.

  5. Click File > Save.
    The User Security Model has been saved.


Removing User Functions from Roles

You can remove unnecessary User Functions from Roles.

To remove a User Function from a Role

  1. Open the Access Management window and click the Role button on the upper toolbar.
    The list of Roles appears in the upper left pane.

  2. Click the User Function button on the lower toolbar.
    The list of User Functions appears in the lower left pane.

  3. Select the Role with the User Function you want to remove.

  4. Uncheck the UserFunction that you want to remove from the Role you selected in step 3.
    The User Function is no longer associated with the selected Role.

  5. Click File > Save.
    A window confirms the save.

  6. Click OK.


Setting ToolBar Permissions

You can define which ToolBar functions belong to a User Function (which then affects the Users who belong to Roles with access to that User Function). ToolBar functions represent individual functions within the Designer, such as copy, paste, or create new process.

You can either grant or restrict permission to ToolBar items.

To grant a User or Role access to a ToolBar

  1. Open the Access Management window and click the User Function button.
    The list of User Functions appears in the upper left pane.

  2. Select the User Function that you want to add ToolBar function to.

  3. Click the ToolBar button on the lower toolbar.
    A list of all available ToolBar functions appear in the bottom left pane.

  4. Select the ToolBar function to which you want to grant access.

    Example:
    To display ConfigurationManagement, you'll want to turn on the BUSINESSCALENDAR, DEPENDENTLISTMANAGEMENT, GEOGRAPHYMANAGEMENT, GEOTIMEZONE, LISTMANAGEMENT, and USERMANAGEMENT.

    Note:
    By default, all of the ToolBar options are set to visible.

  5. Click the Set Visible button [image].

  6. Click File > Save.
    Users with this assigned User Function will now be able to use the ToolBar function.

  7. If needed, assign the User Function to a Role in order to apply the ToolBar permissions.

To restrict a User or Role from seeing the ToolBar

  1. Open the Access Management window and click the User Function button.
    The list of User Functions appears in the upper left pane.

  2. Select the User Function that you want to remove a ToolBar function from.

  3. Click the ToolBar button on the lower toolbar.
    A list of all available ToolBar functions appear in the bottom left pane.

  4. Select the ToolBar function for which you want to restrict access.

    Example:
    To Hide ConfigurationManagement, you'll want to turn off the BUSINESSCALENDAR, DEPENDENTLISTMANAGEMENT, GEOGRAPHYMANAGEMENT, GEOTIMEZONE, LISTMANAGEMENT, and USERMANAGEMENT.

    Note:
    By default, all of the ToolBar functions are set to visible.

  5. Click the Set No Access button [image].

  6. Click File > Save.
    Users in this Role will no longer have access to this ToolBar item.

  7. If needed, assign the User Function to a User or Role in order to apply the toolbar permissions.

Related Topics

About Access Management


Adding Users

You can use Access Management to add new Users to BPM Suite. Five fields in the User Profile are required (1) selected user name, (2) first name, (3) last name, (4) Email address, and (5) password; however, you may also enter other auxiliary user information if your process solution requires it.

Important Note

In order for a manual activity to make use of the business calendar, a User's profile must include a value for State and Zip Code. These are not required values for all User profiles, so you should use Access Management to ensure the profiles include this information.

Caution: A known limitation exists in the New User Profile window. If you lock your computer (which may happen automatically after a period of inactivity), then enter your password to log back in, the BPM Designer application will crash and any unsaved work will be lost. Please be sure to save your work frequently and do not allow Windows to lock while creating or modifying a User profile.

To add a user

  1. Open the Access Management window and click the User button on the upper toolbar [image].

  2. Click the Add button [image].
    The New User Profile window appears.

  3. Enter the User's name, as you want it to appear in BPM Suite, in the User Name field.

  4. Enter a title for the User in the Title field.

  5. Enter the User's first name in the User First Name field.
    The User's first name appears in the User Full Name field.

  6. Optionally, enter the User's middle initial in the User Middle Initial.

  7. Enter the User's last name in the User Last Name field.
    The User's full name appears in the User Full Name field.

  8. Enter the User's Email address in the Email Address field.

    Note:
    The Email address field is not required, but it is necessary if you want to send the User notifications by email.

  9. Enter any additional contact information you want in the Profile.

  10. Click OK.
    The Set Initial Password window appears.

  11. Enter the user's default password in the New Password field.

    Note:
    Later, remind the user to change his or her password after logging in to BPM Designer or BPM Web for the first time.

  12. Enter the user's default password again in the Confirm New Password field.

  13. Click OK.
    A message appears letting you know the password has been set.

  14. Click OK.
    The new user's name appears in the list of users in the upper left pane on the Access Management window.


Assigning Users to Roles

You can assign Users to one or more Roles, giving them the permissions and job responsibilities associated with each role.

Note:
You can assign a User to multiple Roles, depending on the User's job responsibilities and the Roles you have defined.

To add a User to a Role

  1. Open the Access Management window and click the User button [image] on the upper toolbar.
    The list of Users appears in the upper left pane.

  2. Click the Role button [image] on the lower toolbar.
    The list of roles appears in the lower left pane.

  3. From the list of users, select the user you want to assign to a role.

  4. From the list of roles, click the check box to the left of the role that you want to assign to the user you selected in step 3.
    A checkmark appears in the check box, indicating that the user has been assigned to that role.

  5. Click the File menu and select Save.
    A message appears stating that the User Security Model has been updated.

  6. Click OK.
    The User now has access to rights associated with that Role.


Editing User Properties

After you create a User, you can edit the properties of that User profile.

Important Note

In order for a manual activity to make use of the business calendar, a User's profile must include a value for State and Zip Code. These are not required values for all User profiles, so you should use Access Management to ensure the profiles include this information.

Caution: A known limitation exists in the New User Profile window. If you lock your computer (which may happen automatically after a period of inactivity), then enter your password to log back in, the BPM Designer application will crash and any unsaved work will be lost. Please be sure to save your work frequently and do not allow Windows to lock while creating or modifying a User profile.

To edit a user's properties

  1. Open the Access Management window and click the User button [image] on the upper toolbar.
    A list of Users appears in the upper-left pane.

  2. Double-click the user you want to edit.
    The User's profile appears.

  3. Edit the following fields as necessary:

    For the

    Do the following

    User Name

    Enter the User's new User Name.

    Title

    Enter the User's job title.

    User First Name

    Enter the User's first name.

    User Middle Initial

    Enter the User's middle initial. (Optional.)

    User Last Name

    Enter the User's last name.

    User Full Name

    Nothing. The full name is automatically created.

    Street Address

    Enter the User's street address.

    City

    Enter the User's city.

    State

    Enter the User's state.

    Zip Code

    Enter the User's zip code.

    Business Phone

    Enter the User's business phone number.

    Wireless Phone

    Enter the User's wireless phone number.

    Fax

    In the Fax field, enter only the digits for the user's fax number.

    Out of Office

    Check this box if the User is unavailable to complete tasks.

    Manager User ID

    Click the drop-down list and select the User who is considered the manager of this User. This field is used in the User Type Assignment activity to assign work to a User's manager.

    Email address

    Enter the User's email address.

    SMS Address

    Enter the User's SMS address.

    ICQ Messenger Address

    Enter the User's ICQ address.

    MSN Messenger Address

    Enter the User's MSN Messenger address.

    AOL AIM Address

    Enter the User's AOL Instant Messenger address.

    Yahoo Messenger Address

    Enter the User's Yahoo Messenger address.

    AOL AIM Messenger Screen Name

    Enter 1 in this field if BPM suite should use the User's AIM screen name

    MSN Messenger Passport Login

    Enter 1 in this field if BPM suite should use the User's MSN Messenger address.

    Yahoo! Instant Messenger Screen Name

    Enter 1 in this field if BPM suite should use the User's Yahoo! screen name.

    ICQ Instant Messenger Screen Name

    Enter 1 in this field if BPM suite should use the User's ICQ screen name.

    Time Zone

    Click the drop-down list and select the User's time zone. The time zone is used when BPM Suite calculates escalation and timeout intervals for Manual activities.

    Password

    After you enter the user's information and click OK, a Set Initial Password window appears. Set the user's initial password.

  4. Click OK.
    The User profile saves and closes.


Removing Users

If a user will no longer be using BPM Designer or BPM Web, you can remove that user.

Important:

After removing a user, the user will no longer be able to access BPM Designer or BPM Web, and that user's tasks will not be completed unless they are assigned to a different user.

To remove a user

  1. Open the Access Management window and click the User button [image] on the upper toolbar.
    The list of users appears in the upper left pane.

  2. From the list of users, select the one you want to remove.

  3. Click the Remove button [image].
    A message box appears asking if you are sure you want to remove this User.

  4. Click Yes.
    The user is removed.

  5. From the File menu, click Save.
    The user is no longer available.


Removing Users from Roles

If a user does not belong to a role any longer, you can remove that user from the role.

Important:
Removing a user from a role does not remove the user from BPM Suite. The user will still have access to BPM Suite, unless you remove the user from BPM Suite.

To remove a user from a role

  1. Open the Access Management window and click the Role button on the upper toolbar [image].
    A list of roles appears in the upper left pane.

  2. Click the User button on the lower toolbar [image].
    A list of users appears in the lower left pane.

  3. From the list of roles, click the role that you want to remove from (a) User(s).

  4. From the list of users, click the check box to the left of the User you want to remove from the role you selected in step 3.
    The checkmark disappears from the check box, which indicates that the user has been removed from the role.

  5. From the File menu, click Save.
    The user has been removed from the role.


About Access Management

You can use Access Management to create, edit, and remove Users, Roles, and User Functions. Users are assigned to Roles. UserFunctions are assigned to Roles, which determines what rights the Users of the Role can have.

Each Role has its own permissions associated with it depending on the UserFunctions available to it.

Managing Users

A User is an individual with access to BPM Suite. Each User is assigned a unique user name and password.

  • Adding Users

  • Editing User Properties

  • Adding Users to Roles

  • Removing Users from Roles

  • Removing Users from BPM Suite

  • Mapping BPM Suite Roles to Active Directory Groups

Managing Roles

A Role is a group of Users who have the same job function and require the same kind of access to BPM Suite.

  • Adding Roles

  • Editing Role Properties

  • Removing Roles

Edit the Roles Org Chart

The Roles Org Chart allows you to graphically model role hierarchy within your organization. BPM Suite uses the Roles Org Chart to manage Manual Activity assignment and escalation.

  • About the Roles Org Chart

  • Understanding the Roles Org Chart toolbar

  • Adding Roles to the Roles Org Chart

  • Adding and Linking Roles

  • Adding Subordinates to a Role

  • Setting a Role's Parent

  • Viewing Role Properties

  • Removing Roles from the Org Chart

  • Deleting Role Links

  • Changing Line Type

Managing User Functions

A User Function is a collection of security settings that determines a User's rights. User Functions are assigned to Roles to define toolbar access and system privileges.

  • Adding User Functions

  • Editing User Function Properties

  • Adding User Functions to Roles

  • Removing User Functions from Roles

  • Removing User Functions from BPM Suite

Managing Role permissions

A User's rights are based on that User's Role. The rights associated with a Role are defined by a collection of UserFunctions. For example, you can define a User's ability to access toolbars.

  • Setting Toolbar Permissions

Related Topics

Opening the Access Management window


Accessing the Access Management window

Opening the Access Management window

You can access the Access Management window using the Configuration Management menu.

To access the Access Management window

  • Click the Configuration Management menu and select the Manage Users and Roles button [image].
    The Access Management window opens.


About Administrator Setup

Some features of BPM Designer should be configured by IT personnel before Business Users access the program.

Features that IT Personnel Should Configure

  • Users, Roles, and Privileges

  • Using Active Directory with BPM Suite

  • The Scripting Activity

  • The Command-line Activity

  • The Web Service Invoker

Demo Movies

Flash-based movie demos of BPM Designer can be accessed along with this User Guide. If you prefer to see some of the basic functions of BPM Designer as movies, these demos will introduce you quickly. Learn more about BPM Designer Demos.

Relevant Movies:

  • Managing Users and Roles


Understanding User Privileges and Roles

To define a User's access rights in BPM Designer, you must first understand how privileges work. In BPM Designer, privileges are defined in layers of granularity.

Toolbar Items

At the smallest level, privileges are defined by Toolbar Items. A Toolbar Item is an individual, discrete function in BPM Designer (e.g. Copy, Paste, and Create New Process). You cannot add or edit Toolbar Items.

User Functions

User Functions are compilations of Toolbar Items.

Roles

Each Role is made up of Users and has access to a common set of User Functions.

Users

Once you have created a Role and defined which User Functions it can access, you can assign a User to that Role. The User then gains all the privileges associated with that Role.

Each User belongs to at least one Role; however, a User can be assigned to more than one Role. In that case, the User selects one Role to identify with at login. To change to a different Role, the User should log out and log back in.

Roles Org Chart

The Roles Org Chart does not define privileges, but it is closely related to Users and Roles. The Roles Org Chart models the hierarchy between various Roles. For example, you could create an Org Chart that shows the Regional Manager having responsibility for Local Managers, who have responsibility for Team Leaders, who have responsibility for the Developers, Designers, Writers, and Sales team members they manage.

The organization modeled in Roles Org Chart is used to define which managers receive tasks when they are escalated and which managers have visibility into their subordinates' task lists.

Defining User Privileges and Roles

The Access Management tool provides the ability to manage Toolbar Items, User Functions, Roles, Users, and the Roles Org Chart. Although Business Analysts should be familiar with these terms and with the Roles Org Chart, this Guide assumes they are actually configured by IT personnel.


About the Create Active Directory Activity

You can use the Create Active Directory activity to create users, groups, and computers in domains running Windows 2000 or Windows 2003 Active Directory.

  • Creating a User in Active Directory

  • Creating a Group in Active Directory

  • Creating a Computer in Active Directory

Required Auxiliary Topics

Before you begin configuring a Create Active Directory activity, make sure to complete the following:

  • Create Data Items that will store values to be used when creating objects


Creating a Computer in Active Directory

An Active Directory computer is an object that represents a resource on a network, which might be a user's laptop, a desktop computer, or a server.

To create a computer in Active Directory

  1. Add the Create Active Directory activity to the designer canvas and complete the common activity properties.

  2. Click the Create Active Directory tab.

  3. Configure the Active Directory Connection Settings.

  4. From the drop-down list in the Active Directory object group box, select Computer Object.
    The activity queries Active Directory for available attributes and populates the Attribute Name column of the grid with those values.

  5. From the Attribute Name drop-down list column of the grid, select an attribute.

    Note    : By default, only required attributes are included in the Attribute Name drop-down list column. To view all attributes, click the Only show required attributes check box to remove the check.

  6. In the Source column, select one of the following options as the source of the attribute:

    • Data Item Display Value
      If you select Data Item Display Value, you will have to select a Data Item from the Value column. The selected Data Item's Display Value will be used when the object is created.

    • Data Item Value
      If you select Data Item Value, you will have to select a Data Item from the Value column. The selected Data Item's Value will be used when the object is created.

    • Constant
      If you select Constant, then in the Value column, you will have to enter the value that you want the selected attribute to have.

  7. From the Value column, select a Data Item if you selected Data Item Display Value or Data Item Value or enter a value if you selected Constant from the Source drop-down list column.

  8. Repeat steps 5 through 7 until you have at least configured the four required attributes.

    Note    : Click here to view the required computer attributes in a default environment.

  9. Click OK.
    The Properties for Activity window closes.

Related topics

About the Create Active Directory Activity


Creating a Group in Active Directory

An Active Directory group is an object that represents a collection of users, computers, and other groups on a network.

To create a group in Active Directory

  1. Add the Create Active D irectory activity to the designer canvas and complete the common activity properties.

  2. Click the Create Active Directory tab.

  3. Configure the Active Directory Connection Settings.

  4. From the drop-down list in the Active Directory object group box, select Group Object.
    The activity queries Active Directory for available attributes and populates the Attribute Name column of the grid with those values.

  5. From the Attribute Name drop-down list column of the grid, select an attribute.

    Note    : By default, only required attributes are included in the Attribute Name drop-down list column. To view all attributes, click the Only show required attributes check box to remove the check.

  6. In the Source column, select one of the following options as the source of the attribute:

    • Data Item Display Value
      If you select Data Item Display Value, you will have to select a Data Item from the Value column. The selected Data Item's Display Value will be used when the object is created.

    • Data Item Value
      If you select Data Item Value, you will have to select a Data Item from the Value column. The selected Data Item's Value will be used when the object is created.

    • Constant
      If you select Constant, then in the Value column, you will have to enter the value that you want the selected attribute to have.

  7. From the Value column, select a Data Item if you selected Data Item Display Value or Data Item Value or enter a value if you selected Constant from the Source drop-down list column.

  8. Repeat steps 5 through 7 until you have at least configured the seven required attributes.

    Note    : Click here to view the required group attributes in a default environment.

  9. Click OK.
    The Properties for Activity window closes.

Related topics

About the Create Active Directory Activity


Creating a User in Active Directory

An Active Directory user is an object that represents a person that has access to the network.

To create a user in Active Directory

  1. Add the Create Active Directory activity to the designer canvas and complete the common activity properties.

  2. Click the Create Active Directory tab.

  3. Configure the Active Directory Connection Settings.

  4. From the drop-down list in the Active Directory object group box, select User Object.
    The activity queries Active Directory for available attributes and populates the Attribute Name column of the grid with those values.

  5. From the Attribute Name drop-down list column of the grid, select an attribute.

    Note    : By default, only required attributes are included in the Attribute Name drop-down list column. To view all attributes, click the Only show required attributes check box to remove the check.

  6. In the Source column, select one of the following options as the source of the attribute:

    • Data Item Display Value
      If you select Data Item Display Value, you will have to select a Data Item from the Value column. The selected Data Item's Display Value will be used when the object is created.

    • Data Item Value
      If you select Data Item Value, you will have to select a Data Item from the Value column. The selected Data Item's Value will be used when the object is created.

    • Constant
      If you select Constant, then in the Value column, you will have to enter the value that you want the selected attribute to have.

  7. From the Value column, select a Data Item if you selected Data Item Display Value or Data Item Value or enter a value if you selected Constant from the Source drop-down list column.

  8. Repeat steps 5 through 7 until you have at least configured the seven required attributes.

    Note    : Click here to view the available user attributes in a default environment.

  9. Click OK.
    The Properties for Activity window closes.

Related topics

About the Create Active Directory Activity


About the Delete Active Directory Activity

You can use the Delete Active Directory activity to delete users, groups, and computers from domains running Windows 2000 or Windows 2003 Active Directory.

  • Deleting an Object from Active Directory using a Common Name stored in a Data Item

  • Deleting an Object from Active Directory using a static Common Name


Deleting an Object from Active Directory using a static Common Name

A user, group, or computer can be removed from Active Directory if you know the object's Common Name.

Note: An object's Common Name is the object's unique identifier in the domain.

To delete an object from Active Directory using a static Common Name

  1. Add the Delete Active Directory activity to the designer canvas and complete the common activity properties.

  2. Click the Delete Active Directory tab.

  3. Configure the Active Directory Connection Settings.

  4. Click the Enter Common Name radio button in the Object to delete group box.
    The drop-down list changes to a text box.

  5. In the text box, enter the Common Name of the object you want to delete.

  6. Click OK.
    The Properties for Activity window closes.

Related topics

About the Delete Active Directory Activity


About the Retrieve Active Directory Activity

You can use the Retrieve Active Directory activity to get information about users, groups, and computers from domains running Windows 2000 or Windows 2003 Active Directory.

  • Retrieving Object Information from Active Directory using a Common Name stored in a Data Item

  • Retrieving Object Information from Active Directory using a Static Common Name

Required Auxiliary Topics

Before you begin configuring a Retrieve Active Directory activity, make sure to complete the following:

  • Create Data Items that will store the object information the activity will retrieve


About the Update Active Directory Activity

You can use the Update Active Directory activity to update information about users, groups, and computers in domains running Windows 2000 or Windows 2003 Active Directory.

  • Updating Object Information in Active Directory using a Common Name stored in a Data Item

  • Updating Object Information in Active Directory using a Static Common Name

Required Auxiliary Topics

Before you begin configuring a Update Active Directory activity, make sure to complete the following:

  • Create Data Items that will store values to be used when updating objects


Updating Object Information from Active Directory using a Static Common Name

Updating Object Information in Active Directory using a Static Common Name

You can update information about Active Directory users, groups, and computers if you know the object's Common Name.

Note: An object's Common Name is the object's unique identifier in the domain.

To update information about an object in Active Directory using a static Common Name

  1. Add the Update Active Directory activity to the designer canvas and complete the common activity properties.

  2. Click the Update Active Directory tab.

  3. Configure the Active Directory Connection Settings.

  4. Click the Enter Common Name radio button in the Object and object type to update group box.
    The drop-down list to the left of the radio buttons changes to a text box.

  5. In the text box, enter the Common Name of the object you want to update.

  6. From the Object type drop-down list, select the type of object being updated.
    The activity queries Active Directory for available attributes and populates the Attribute Name column of the grid with those values.

    Note    : The attributes available in the Map Data Items to Active Directory attributes grid change depending on the object selected.

  7. In the empty row of the grid in the Map Data Items to Active Directory attributes group box, select one of the object's attributes to update.
    A new row is added to the grid below the selected row.

  8. In the Source column, select one of the following options as the source of the updated value:

    • Data Item Display Value
      If you select Data Item Display Value, you will have to select a Data Item from the Value column. The selected Data Item's Display Value will be used to update the selected attribute.

    • Data Item Value
      If you select Data Item Value, you will have to select a Data Item from the Value column. The selected Data Item's Value will be used to update the selected attribute.

    • Constant
      If you select Constant, then in the Value column, you will have to enter the value that you want the selected attribute to have.

  9. In the Value column, depending on the source, either select a Data Item or enter the value

  10. Repeat steps 7 through 9 to update additional attributes with values.

    Note    : You can only select each attribute once.

  11. Click OK.
    The Properties for Activity window closes.

Related topics

About the Update Active Directory Activity


CAP - Active Directory Activities

  1. Click the Active Directory category in the Toolbox.

  2. Double-click the activity you want to add, or drag it to the Canvas.
    The activity is added to the process.

  3. Open the Properties for the activity (double-click the activity or right-click and select Activity Properties).
    The Properties window appears.

  4. Complete the common activity properties.


Configure the Active Directory Connection Settings

Before configuring an Active Directory activity, you have to configure the Active Directory Connections Settings. After configuring the Active Directory Connection Settings, you can map values to Active Directory attributes.

To configure the Active Directory Connection Settings

  1. While configuring one of the Active Directory activities, click the Connection button.
    The Active Directory Connection Settings window opens.

  2. In the Username field, enter the username of a domain administrator.

    Important    : The selected user must be a domain administrator. If not, the Active Directory activities will not have permission to make changes to Active Directory. You can browse for a user by clicking the ellipses button next to the Username field.

  3. In the Password field, enter the password for the domain administrator you entered in the Username field.

  4. In the Hostname field, enter the hostname for the domain.

    Note    : When the Active Directory Connection Settings window opens for the first time, it will try to determine the hostname using your computer settings. You should validate the hostname if it exists.

  5. To validate the connection settings, click the Validate User button.
    A message box appears to tell you if the user was valid or not.

  6. Click OK.
    The message box closes.

  7. When the username and password are valid, click OK.
    The Active Directory Connection Settings window closes.


Required Active Directory Attributes for Computers

The following attributes are available when creating, retrieving, and updating Active Directory users.

Attribute | Description
Common Name (Common-Name) | Specifies the name of the computer object in Active Directory.
Instance Type (Instance-Type) | Specifies how the object is instantiated on a particular server. The value of this attribute can differ between replicas even if the replicas are in sync.
Category (Object-Category) | Specifies the category used to group objects of this or derived classes.
Class (Object-Class) | Specifies the list of classes from which the class to which this computer belong is derived.


Required Active Directory Attributes for Groups

The following attributes are available when creating, retrieving, and updating Active Directory users.

Attribute | Description
Common Name (CN) | Specifies the name of the user object in Active Directory. This name is the object's Relative Distinguished Name (RDN).
Category (Object-Category) | Specifies the category used to group objects of this or derived classes.
Class (Object-Class) | Specifies the list of classes from which the class to which this computer belong is derived.
Group Type (Group-Type) | Contains a set of flags that define the type and scope of a group object. 1 specifies that the group was created by the system. 2 specifies the group has global scope. 4 specifies the group has domain local scope. 8 specifies the group has universal scope. 2147483648 specifies the group is a security group.
Instance Type (Instance-Type) | Specifies how the object is instantiated on a particular server. The value of this attribute can differ between replicas even if the replicas are in sync.
SAM Account Name (SAM-Account-Name) | The logon name used to support clients and servers running older versions of the operating system, such as Windows NT 4.0, Windows 95, Windows 98, and LAN Manager. The value must be less than 20 characters to support older clients.
Security Identifier (SID) (Object-Sid) | A binary value that specifies the security identifies (SID) of the user. The SID is a unique value used to identify the user as a security principal.


Required Active Directory Attributes for Users

The following attributes are available when creating, retrieving, and updating Active Directory users.

Attribute | Description
Common Name (CN) | Specifies the name of the user object in Active Directory. This name is the object's Relative Distinguished Name (RDN).
Account Name (sAMAccountName) | Specifies a string that is the name used to support clients and servers from a previous version of Windows. The sAMAccountname should be less than 20 characters to support clients from a pervious version of Windows. The sAMAccountname must be unique among all objects within a domain. If the domain server is running Windows Server 2003, the sAMAccountName value is optional. The server will create a random sAMAccountName value if a value is not specified.
Account Expires (accountExpires) | Specifies when the account will expire. By default, the value is TIMEQ_FOREVER, which indicates that the account will never expire. This object represents a date.
Category (objectCategory) | Specifies the user category to which the new user will belong. Typically the category is Users.
Name (name) | Specifies the user's display name.
Password Set (pwdLastSet) | Specifies when the user's password was last set. The default is zero, which indicates that the user must change their password at next logon. If not zero, the value is a date.
Account Control (userAccountControl) | Contains values that determine several logon and account features for the user. If using Constant as the source, a window opens with the available options/flags. By default, the account is disabled (UF_ACCOUNTDISABLED), no password is required (UF_PASSWD_NOTREQD), and the account is a normal account (UF_NORMAL_ACCOUNT).
Group Membership (memberOf) | Specifies the group or groups that the user is a direct member of. The default value is Domain Users.


About the Calendar Delay Activity

The Calendar Delay activity allows you to account for holidays / events and time zone differences when delaying a process relative to a time or for a set time period. You can delay an activity relative to a preexisting time and time zone, or you can use Data Items that store a time or time zone ID.

Follow the links below to learn how to configure a Calendar Delay activity.

  • Delaying Activities While Accounting for Holidays and Time Zones

  • Using Time Zone and Time Data Items to Delay Activities

Required Auxiliary Topics

If you are going to configure a Calendar Delay activity using Data Items, you will need to first create the necessary Data Items. Follow the link below to learn how to create Data Items.

  • Creating Data Items


Delaying Activities With Holidays Time Zones

Delaying Activities While Accounting for Holidays and Time Zones

Using the Calendar Delay activity, you can delay a process based on the holiday/event schedule and the time zone of a specific location. For example, if a Calendar Delay activity is set to occur on a Monday, but that day is a holiday for the geographic location it is set for, the Calendar Delay activity will postpone the execution of the delay until work resumes on the following day (Tuesday).

Furthermore, by setting a time zone the activity will account for time zone differences between each geographic location. For instance, a delay set for a 12:00 PM California time will automatically adjust to delay at 12:00 PM New York time if New York is selected as a time zone.

To delay activities relative to holidays and time zones

  1. Add the Calendar Delay activity to the designer canvas and complete the common activity properties.

    Note:
    Completing common activity properties is essential to create an organized and functional process.

  2. Click the Calendar Delay Properties tab.

  3. Click the Delay Relative to drop-down list and select (Now).
    The Delay relative to a specific Data Item drop-down list is grayed out.

  4. Enter the amount of time you want to delay the process in the Days, Hours, and Minutes fields (delay is relative to the time that the Delay activity starts).

  5. Click the Calendar Settings sub-tab.

  6. Click the Holiday Geography to Use when Calculating Delay drop-down list and select the abbreviation for the geographic location whose holidays you want to account for in the delay.
    The Calendar Delay activity will account for holiday time of the geographic location you selected.

  7. Click the Use Standard Time Zone option.

  8. Click the Time zone to use drop-down list and select the time zone where you want the delay to execute.
    The Calendar Delay activity will execute according to the time zone you selected.

  9. Click OK to close the Properties window.


Using Time Zone and Time Data Items to Delay Activities

This Data Item Time value stores a specific time that will not change according to when the delay activity starts.

Example
If the Delay activity begins at 12:00 PM, and the Data Item stores the time 5:00 PM, then the process will delay for five hours, until 5:00 PM. But, if the Delay activity begins at 4:00 PM, then the process will delay for only one hour, until 5:00 PM.

Follow the example syntax below when setting a specific time value.

"5:00:00 PM" (Quotations are essential)

This Data Item Time value adds a time amount you specify to the current system clock. Use the following syntax when setting this variable.

DateAdd ("<variable>", <variable number>, Time)

In the <variable> field, type the syntax for the variable to which you want to add (s= seconds, n = minutes, h = hours, yyyy = years, m = months ) and in the <variable number> field type the number of the variable that you to want add.

Using Time Zone and Time Data Items to Delay Activities

You can use the Calendar Delay activity to delay a process based on the time zone and time value stored in Data Items.

Note:
To delay relative to a Time Zone using a Data Item, the Data Item will have to be populated with a Time Zone ID. A Time Zone ID can be any value under the TimeZoneDisplayName column in the Sys_TimeZoneDisplayNames list, found in List Management.

To use time zone and time Data Items to delay activities

  1. Add the Calendar Delay activity to the designer canvas and complete the common activity properties.

    Note:
    Completing common activity properties is essential to create an organized and functional process.

  2. Click the Calendar Delay tab.

  3. Click the Delay Relative to drop-down list and select (Data Item).

  4. Click the Delay Relative to a Specific Data Item drop-down list and select a Data Item that holds (or will hold) the time you want to delay an activity branch until.

    Note:
    There are two ways to set a time Data Item value and both affect the Delay activity differently. The two types of time Data Item values are:

      • A Specific Time Value

      • A "Relative to a System Clock" Time Value

  5. If you want the process to delay additional time relative to the time stored in the Data Item, enter the time for which you want to delay the process using the Days, Hours, and Minutes fields.

    Example
    If the Data Item is storing the time 12:00 PM, and you add an additional 2 hours and 10 minutes onto the delay, then the process will be delayed until 2:10 PM.

  6. Click the Calendar Settings sub-tab.

  7. Click the Holiday Geography to Use when Calculating Delay drop-down list and select the geographic location whose holidays you want to account for in the delay.
    The Calendar Delay activity will account for holiday time of the geographic location you selected.

  8. Select the Use the Data Item containing the Time Zone ID option.
    The Data Item to use drop-down list becomes active.

  9. Click the Data Item to use drop-down list and select the Data Item that is holding (or will hold) the Time Zone ID that you want the Calendar Delay activity to execute in.

    Note:
    To allow a user to populate a Data Item with a correct Time Zone Display Name, associate a Data Item with the Sys_TimeZoneDisplayNames list via the Data Item Management window. As a result, a user will be able to select a Time Zone ID from a drop-down list and populate the Data Item through BPM Web.

  10. Click OK to close the Properties window.


About the Command-Line Activity

You can use the Command-Line activity to execute code in Windows that can only run through a Windows command prompt. This activity allows you to run .exe files and then store the returned information in a Data Item.

Note: The Command-line Activity is not able to execute command lines that use operators. If you need to execute a command line that includes operators, you can put the command-line into a batch file. The Command-line Activity can then execute any batch file.

You can also insert Data Items into the command, allowing you to configure command prompts that will use information produced earlier in the process.

Follow the links below to view instructions on running Windows commands.

  • Running a Windows Command

  • Running a Windows Command in a Specified Working Directory

Required Auxiliary Topics

Before you configure a Command-Line activity, you need to create Data Items that will complete the command-line prompt and store the information the activity will produce.

  • Creating Data Items


Running a Windows Command

The Command-Line activity allows you to run Windows commands on the BPM Server.

Note: The Command-line Activity is not able to execute command lines that use operators. If you need to execute a command line that includes operators, you can put the command-line into a batch file. The Command-line Activity can execute any batch file.

To run a Windows command

  1. Add the Command Line activity to the designer canvas and complete the common activity properties.

    Note:
    Completing common activity properties is essential to create an organized and functional process.

  2. Click the Command-line tab.

  3. Enter a Windows prompt command in the Command field.

    Note:
    Fully qualify the command by beginning it with the directory that you should issue the command in.

    Example:
    C:    MailProgram.EXE

  4. Optional: To insert Data Items into the command, place your cursor where you want to insert a Data Item, select a Data Item from the Available Data Items list, and click either Insert Display Value or Insert Value.

  5. Click the Which Data Item should receive the return code from this command? drop-down list and select the Data Item that will store the return code from the command.

  6. Click OK to close the Properties window.


Running a Windows Command in a Specified Working Directory

When using a Command-Line activity, you may need to run the command in a directory other than the default. To run a command outside of the default directory, specify the working directory that you want to run the command in.

Note: The Command-line Activity is not able to execute command lines that use operators. If you need to execute a command line that includes operators, you can put the command-line into a batch file. The Command-line Activity can execute any batch file.

To run a Windows command in a specified working directory

  1. Add the Command Line Activity to the designer canvas and complete the common activity properties.

    Note:
    Completing common activity properties is essential to create an organized and functional process.

  2. Click the Command-line tab.

  3. Enter a Windows prompt command in the Command field.

    Note:
    Fully qualify the command by beginning it with the directory that you should issue the command in.

    Example:
    "C:\MailProgram.EXE"

  4. Optional: To insert Data Items into the command, place your cursor where you want to insert a Data Item, select a Data Item from the Available Data Items list, and click either Insert Display Value or Insert Value.

  5. Click the Use specific start-in location option.
    The Start-in field becomes active.

  6. Enter the Windows working directory and level where you want your command to start in the Start-in field.

  7. Click the Which Data Item should receive the return code from this command? drop-down list and select the Data Item that will store the return code from the command.

  8. Click OK to close the Properties window.


About the Connection Node Activity

Use Connection Node activities to link multiple parent tasks to the same child task and to create branches in the process definition. The connection node lists the activities that have a link to it and allows you to configure how each activity will pass information through the connection node.

Important:

Unlike other tasks in the Process Designer toolbox, connection nodes have a single property: Task Dependencies. In the Task Dependencies window you can view the parent activities associated with the node; the Connection Node can be thought of as the child activity. To define the appropriate dependency types, click the icons in the Dependency Type column.

Follow the links below to learn how to use a Connection Node:

  • Using a Connection Node

  • Allowing the System to Auto-Create a Connection Node


Allowing the System to Auto-Create a Connection Node

You do not have to manually place a Connection Node onto the designer canvas and connect activities to it. Instead, allow BPM Designer to automatically create a Connection Node and link activities to it.

To allow the system to auto-create a connection node

  1. Identify multiple parent activities that you want to link to a single child activity.

  2. Link one of the parent activities to the child activity.

  3. Link another parent activity to the same child activity in step 2.
    The Activity Dependency window opens.

    Note:
    The Activity Dependency window will open for each additional activity you link to the child process.

  4. Set the Dependency Types of the two activities.

  5. Link any additional parent activities to the child activity and complete their dependency types.

  6. Click OK to close the Activity Dependency window.


Using a Connection Node

Wait On Task is the default option. This tells the process to wait for the activity to complete before continuing. If there are multiple activities with the Wait On Task option selected, then those activities must complete before the process will continue.

Note: This is a good way to bring the flow of a process back together after taking multiple paths.

This option is set automatically if the link coming into the connection node specifies that is has a Wait On Task type of Conditional. If so, the link will have a logical branch expression to check before moving continuing with the connection node.

This option can be used if the process branched previously and had the option to take one or many paths of execution.

Note:
If setting the connection node to Conditional Wait before setting the link's properties, then you will have to reopen the link's properties and select a Logical Branch to Test. Use the same logical expression located earlier on this path.

Selecting the Do No Wait On Task option allows the connection node to continue before the other activities connected to the connection node have completed.

This option can be used if the process branched previously and took a single path of execution.

Using a Connection Node

Using a Connection node requires that you configure its dependency types. In the Connection Node activity's Activity Dependency window, you can select one of three dependency types for each activity that connects to the Connection Node.

The three dependency types are (1) Wait on Task - The Connection Node will wait for the previous task to complete before starting the next task, (2) Conditional Wait - The Connection Node will wait until a predefined condition in the previous task is met before starting the next task, and (3) Do Not Wait on Task - The Connection Node will not wait for the previous task to complete before starting the next task.

To use the Connection Node

  1. Add the Connection Node Activity to the designer canvas and link parent activities to it.
    The Connection Node's Activity Dependency window opens.

  2. In the Activity Dependency window, click the row of the activity for which you want to update the Dependency Type.
    The dependency type of the activity changes every time you click its row.

    Note:
    The dependency types cycle in the following order:

    1) Wait On Task - Indicated by a solid arrow head

    2) Conditional Wait- Indicated by an empty arrow head

    3) Do Not Wait On - Indicated by an empty circle

  3. If this connection node will complete more than once in the same process, then check the Allow this connection node to complete more than once check box.

    Note:
    Leaving this check box checked even if the connection node will only complete once in a process will not affect the outcome of the process.

  4. Click OK.
    The Activity Dependency window closes.


About the Delay Activity

You can use the Delay activity to pause processes for a period of time or until a specific time. Follow the links below to view instructions on how to use the Delay activity.

  • Delaying Activities Based on a Set Time Period

  • Delaying Activities Relative to a Time Stored in a Data Item

Required Auxiliary Topics

If you are delaying an activity relative to a time stored in a Data Item, you will have to create a Data Item to store the time value.

  • Creating Data Items


Delaying Activities According to a Set Time Period

Delaying Activities Based on a Set Time Period

If you want to delay a branch of activities based on when the Delay activity starts, configure it using a set time period.

Example

If the Delay activity starts at 2:00 PM, and the delay is 3 hours, it will delay until 5:00 PM. But, if the Delay activity starts at 12:00 PM with the same delay, then it will delay until 3:00 PM (i.e. based on whatever time the Delay activity starts).

To delay activities based on a set time period

  1. Add the Delay activity to the Canvas and complete the common activity properties.

    Note:
    Completing common activity properties is essential to create an organized and functional process.

  2. Click the Delay tab.

  3. Click the Delay Relative to drop-down list and select (Now).
    The Delay relative to a specific Data Item drop-down list becomes inactive.

  4. Enter the time for which you want to delay the process in the Days, Hours, and Minutes fields (the time begins counting when the Delay activity starts).

  5. Click OK to close the Properties window.


Delaying Activities Relative to a Time Stored in a Data Item

This Data Item Time value stores a specific time that will not change according to when the delay activity launches.

Example
If the Delay activity begins at 12:00 PM, and the Data Item stores the time 5:00 PM, then the process will delay for five hours, until 5:00 PM. But, if the Delay activity begins at 4:00 PM, then the process will delay for only one hour, until 5:00 PM.

Follow the example syntax below when setting a specific time value.

"5:00:00 PM" (Quotations are essential)

This Data Item Time value adds a time amount you specify to the current system clock. Use the following syntax when setting this variable.

DateAdd ("<variable>", <variable number>, Time)

In the <variable> field, type the syntax for the variable to which you want to add (s= seconds, n = minutes, h = hours, yyyy = years, m = months ) and in the <variable number> field type the number of the variable that you to want add.

Delaying Activities Relative to a Time Stored in a Data Item

Instead of delaying activities according to a set time after the Delay activity starts, you can delay activities relative to a time stored in a Data Item.

Important:

Make sure to Create a Data Item in which to store the time value.

To delay activities relative to a time stored in a Data Item

  1. Add the Delay activity to the Canvas and complete the common activity properties.

    Note:
    Completing common activity properties is essential to create an organized and functional process.

  2. Click the Delay tab.

  3. Click the Delay Relative to drop-down list and select (Data Item).

  4. Click the Delay Relative to a Specific Data Item drop-down list and select a Data Item that holds (or will hold) the time you want to delay an activity branch until.

    Note:
    There are two ways to set a time Data Item value and both affect the Delay activity differently. The two types of time Data Item values are:

      • A Specific Time Value

      • A "Relative to a System Clock" Time Value

  5. If you want the process to delay additional time relative to the time stored in the Data Item, enter the time for which you want to delay the process using the Days, Hours, and Minutes fields.

    Example
    If the Data Item is storing the time 12:00 PM, and you add an additional 2 hours and 10 minutes onto the delay, then the process will be delayed until 2:10 PM.

  6. Click OK to close the Properties window.


About the GeoCoder Activity

You can assign manual tasks to a User based on that User's geographic location, but sometimes you do not know where a User is located when you design a process. In those cases, you can use the Geography Settings in the Manual Activity to derive the Geography from a Data Item.

To create a Data Item that contains a Geography, you can use the GeoCoder activity. The GeoCoder activity derives a Geography from a GeoCode or a partial address, then output the Geography to a Data Item.

  • Deriving the Geography from a GeoCode

  • Deriving the Geography from a Partial Address


Deriving Geography from a GeoCode

If you know the GeoCode of the Geography you want to put into a Data Item, or if you plan to populate a Data Item with a GeoCode at run time, you can derive the Geography from the GeoCode.

Important:

Make sure to create a Text Data Item to store the Geography.

To derive the Geography from a GeoCode

  1. Add the GeoCoder activity to the designer canvas and complete the common activity properties.

    Note:
    Completing common activity properties is essential to create an organized and functional process.

  2. Click the GeoCoder tab.

  3. Choose either Select or From Data Item for the Geography Set option.
    If you choose Select, use the drop-down list to select a Geography Set now.
    If you choose From Data Item, use the drop-down list to select the Data Item that will contain the name of a Geography Set at run time.

  4. Select the From a GeoCode option.

  5. Choose either Fixed or From Data Item for the GeoCode option.
    If you choose Fixed, enter the numerical value of the GeoCode you want to use.
    If you choose From Data Item use the drop-down list to select the Data Item that will contain the GeoCode at run time.

  6. Click the Output Data Item drop-down list and select the Data Item that you want to contain the name of the Geography that is derived from GeoCode.

  7. Click OK to close the Properties window.


Deriving Geography from a Partial Address

You can derive a Geography from an address. The address doesn't have to be complete in order to determine the correct Geography. Parts of the address can come from Data Items or be entered when you configure the activity.

Important

Make sure to create a Text Data Item to store the Geography.

To derive the Geography from a partial address

  1. Add the GeoCoder activity to the designer canvas and complete the common activity properties.

    Note:
    Completing common activity properties is essential to create an organized and functional process.

  2. Click the GeoCoder tab.

  3. Choose either Select or From Data Item for the Geography Set option.
    If you choose Select, use the drop-down list to select a Geography Set now.
    If you choose From Data Item, use the drop-down list to select the Data Item that will contain the name of a Geography Set at run time.

  4. Select the From a Partial Address option.

    Note:
    Some of the options listed below may not be available, depending on which information you choose to derive from a Data Item. Also, not all options listed below are required. You only need to enter the information that you have available.

  5. Choose either Select or From Data Item for the Country option.
    If you choose Select, click the drop-down list and select the country now.
    If you choose From Data Item, use the drop-down list to select the Data Item that will contain the name of the country at run time.

  6. Choose either None, Manual Entry, or From Data Item for the ZIP/Postal Code option.
    If you choose None, the ZIP/Postal Code will not be taken into consideration.
    If you choose Manual Entry, enter the ZIP/Postal Code now.
    If you choose From Data Item, use the drop-down list to select the Data Item that will contain the ZIP/Postal Code at run time.

  7. Choose either None, Select, or From Data Item for the State/Province option.
    If you choose None, the State/Province will not be taken into consideration.
    If you choose Select, use the drop-down list to select the State/Province now.
    If you choose From Data Item, use the drop-down list to select the Data Item that will contain the name of the State/Province at run time.

  8. Choose either None, Select, or From Data Item for the County option.
    If you choose None, the County will not be taken into consideration.
    If you choose Select, use the drop-down list to select the County now.
    If you choose From Data Item, use the drop-down list to select the Data Item that will contain the name of the County at run time.

  9. Choose either None, Select, or From Data Item for the City option.
    If you choose None, the city will not be taken into consideration.
    If you choose Select, use the drop-down list to select the city now.
    If you choose From Data Item, use the drop-down list to select any Data Item that will contain the name of the city at run time.

  10. Click the Output Data Item drop-down list and select the Data Item that you want to contain the name of the Geography that is derived from GeoCode.

  11. Click OK to close the Properties window.


About the Get File Activity

You can use the Get File activity to retrieve a file from any directory accessible to BPM Suite and then put that file in BPM Suite's file repository. Files that are accessible to BPM Suite generally fall into two categories:

  • Files on a network computer

  • Files on the Web

The Get File activity can read files from either of these locations. This function is useful if your process needs to access a file type (such as an image file) that is not addressed with any other activity. You might also use this activity if you just want to get a document (such as a Word or Excel file) from some location and continue with a process.

The Get File activity can retrieve a single file or multiple files from a network location:

  • Getting a file from a network location

  • Getting multiple files from a network location

You can also use the activity to retrieve a single file from the Web:

  • Getting a file from the Web

Required Auxiliary Topics

When you retrieve a file from a network location or the Web, you need to store that file in a FilePointer Data Item.

  • Creating FilePointer Data Items


  1. Click the Preview Pathname button.

  2. Click the Value field next to each Data Item and enter the value you expect the Data Item will receive when the process runs.

  3. Click the Preview Pathname button.
    The Pathname box displays the pathname that would be used if the process received those Data Item values.

  4. Click OK to close the window.

Getting a File from a Network Location

You can use the Get File activity to retrieve a single file from any networked computer accessible to BPM Suite.

To get a single file from a Network Location

  1. Add the Get File activity to the Canvas and open the Properties window.

  2. Click the Get File tab.

  3. Click in the Pathname box and enter the entire pathname to one file. The pathname should end with a single filename and extension.

    You can also click the Available Data Items drop-down box and select a Data Item that contains a value that you want to make part of the pathname. After you select the Data Item, click the Insert Display Value or Insert Value button. A Data Item place holder will appear in the Pathname field. When the process runs, the actual value of the Data Item will replace the place holder.

    Examples:
    To retrieve a file from a known location on a networked computer.
    \\ServerName\Directory\Folder\Filename.doc
    To retrieve a file from a location that will be determined by Data Items when the process runs.
    \\ServerName\Directory\%DataItem.DisplayValue%\Filename.doc
    To retrieve a file from a location on the server where BPM Engine is installed.
    C:\Documents and Settings\All Users\Filename.doc

  4. If you used Data Items in your pathname, you can click the Preview Pathname button to see what the final Pathname might look like.

  5. Select Copy file(s) or Move file(s).
    Copy file(s)     will create a new copy of the selected file in the BPM Suite repository, and leave the original file in tact.
    Move file(s)     will create a new copy of the selected file in the BPM Suite repository, and delete the original file.

  6. Click the Data Item drop-down list and select the FilePointer Data Item that should contain the file after it is added to the BPM Suite file repository.

    Note:     By default, the Clear Existing option is selected. This removes any other values that might be in the Data Item, so it will only contain the file you are retrieving with this activity. If you want to preserve other values in the Data Item, you can un-select this option.

  7. Optionally, select the Check for errors while getting file option. If you select this option, you can choose a Data Item that will record any file writing errors that occur before the activity fails. For example, "File Not Found", "Permission Denied", etc. The Data Item will not record any errors unless the activity fails.

  8. If you selected the Check for errors while getting file option, click the Data Item drop-down list and select the Data Item that will record the error messages.

  9. Click OK


Getting a File from the Web

When the Get File activity retrieves a file from a Web address, and the pathname does not specify a file name and extension, the activity is unable to tell what kind of file it is retrieving. As a result, it doesn't know how to encode the file. To correct this, the activity compares the retrieved file to a list in List Management. The list (called Sys_ContentType) contains a list of common file extensions and the type of encoding for each extension.

If the Get File activity retrieves a file with an extension in this list, it will encode the file properly. If the extension is not in the list, the file will not work properly.

You (or someone familiar with file encoding types) can expand the functionality of this activity by adding new file extensions and encoding types to this list.

  1. Click the Preview Pathname button.

  2. Click the Value field next to each Data Item and enter the value you expect the Data Item will receive when the process runs.

  3. Click the Preview Pathname button.
    The Pathname box displays the pathname that would be used if the process received those Data Item values.

  4. Click OK to close the window.

Getting a File from the Web

You can use the Get File activity to retrieve a single file from a Web address (http).

To get a single file from a Network Location

  1. Add the Get File activity to the Canvas and open the Properties window.

  2. Click the Get File tab.

  3. Click in the Pathname box and enter the entire pathname to one file. The pathname should end with a single filename and extension.

    You can also click the Available Data Items drop-down box and select a Data Item that contains a value that you want to make part of the pathname. After you select the Data Item, click the Insert Display Value or Insert Value button. A Data Item place holder will appear in the Pathname field. When the process runs, the actual value of the Data Item will replace the place holder.

    Example:
    http://www.bluespringsoftware.com/products/BPM Suite Fact Sheet.pdf

    Note:
    When you retrieve a file from a Web site, you cannot use wild card characters to retrieve more than one file. If you enter a web address with no filename and extension (e.g. http://www.bluespringsoftware.com/), the activity will retrieve the one file that your Web browser would retrieve if you directed it to that address. If you are interested in making full use of this feature, you can read the more technical explanation.

  4. If you used Data Items in your pathname, you can click the Preview Pathname button to see what the final Pathname might look like.

  5. Select Copy file(s). The Get File activity does not allow you to delete files from a directory on the Web.
    Copy file(s)     will create a new copy of the selected file in the BPM Suite repository, and leave the original file in tact.

  6. Click the Data Item drop-down list and select the FilePointer Data Item that should contain the file after it is added to the BPM Suite file repository.

    Note:     By default, the Clear Existing option is selected. This removes any other values that might be in the Data Item, so it will only contain the file you are retrieving with this activity. If you want to preserve other values in the Data Item, you can un-select this option.

  7. Optionally, select the Check for errors while getting file option. If you select this option, you can choose a Data Item that will record any file writing errors that occur before the activity fails. For example, "File Not Found", "Permission Denied", etc. The Data Item will not record any errors unless the activity fails.

  8. If you selected the Check for errors while getting file option, click the Data Item drop-down list and select the Data Item that will record the error messages.

  9. Click OK


  1. Click the Preview Pathname button.

  2. Click the Value field next to each Data Item and enter the value you expect the Data Item will receive when the process runs.

  3. Click the Preview Pathname button.
    The Pathname box displays the pathname that would be used if the process received those Data Item values.

  4. Click OK to close the window.

Getting Multiple Files from a Network Location

You can use the Get File activity to retrieve multiple files from any computer accessible to BPM Suite. To do this, you will use wildcard characters to define a general filename that may match several actual filenames. You can use wildcards to return files with similar names or similar file extensions. However, you cannot return folders within a directory.

To get multiple files from a Network Location

  1. Add the Get File activity to the Canvas and open the Properties window.

  2. Click the Get File tab.

  3. Click in the Pathname box and enter the pathname to the directory where you want to retrieve files. Use the asterisk character (*) as a wild card to define which files in the directory you want to retrieve. Refer to the examples below for more information on how to use the wild card character.

    You can also click the Available Data Items drop-down box and select a Data Item that contains a value that you want to make part of the pathname. After you select the Data Item, click the Insert Display Value or Insert Value button. A Data Item place holder will appear in the Pathname field. When the process runs, the actual value of the Data Item will replace the place holder.

    Examples:
    To retrieve every file in a given directory.
    \\ServerName\Directory\Folder\*
    To retrieve files that have part of their file name in common.
    \\ServerName\Directory\%DataItem.DisplayValue%\*_Account.xls
    To retrieve files that have only their file extension in common.
    \\ServerName\Directory\Folder\*.doc

  4. If you used Data Items in your pathname, you can click the Preview Pathname button to see what the final Pathname might look like.

  5. Select Copy file(s) or Move file(s).
    Copy file(s)     will create a new copy of the selected files in the BPM Suite repository, and leave the original files in tact.
    Move file(s)     will create a new copy of the selected files in the BPM Suite repository, and delete the original files.

  6. Click the Data Item drop-down list and select the FilePointer Data Item that should contain the files after they are added to the BPM Suite file repository.

    Note:     By default, the Clear Existing option is selected. This removes any other values that might be in the Data Item, so it will only contain the files you are retrieving with this activity. If you want to preserve other values in the Data Item, you can un-select this option.

  7. Optionally, select the Check for errors while getting file option. If you select this option, you can choose a Data Item that will record any file writing errors that occur before the activity fails. For example, "File Not Found", "Permission Denied", etc. The Data Item will only record errors if the activity fails.

  8. If you selected the Check for errors while getting file option, click the Data Item drop-down list and select the Data Item that will record the error messages.

  9. Click OK


About the Get User Profile Activity

Some activities require information contained in a User's Profile. For example, an activity may require a User's email address, AOL Instant Messenger address, or his/her manager's User ID.

While designing a process, you may not have access to this information, or you may want BPM Suite to derive the information dynamically. In that case, you can use the Get User Profile activity to retrieve pieces of information from a User's profile and store them in Data Items, allowing you to use that information in subsequent activities.

You can retrieve information from a User's Profile in the following three ways:

  • Retrieve Information from a Specific User's Profile

  • Retrieve Information from the Process Initiator's Profile

  • Retrieve Information from the Process Owner's Profile

Required Auxiliary Topics

If you retrieve information from a specific User's profile, you will need to create a UserID type Data Item to store the User's ID. This allows BPM Suite to reference the User's profile information.

  • Create a User ID Data Item

Also, you will need to create Data Items to store the information you retrieve from the User Profile. The Data Type of the Data Item will need to match the selected User Profile Data (e.g. Text).

  • Creating Data Items


Retrieve Information from a Specific User's Profile

You can use the Get User Profile activity to retrieve information from the User Profile of any BPM User. Although you can view a User's profile by opening Access Management, you might not know which User's profile you want to access when you design the process. Instead, you might want to retrieve information from the profile of a User to be determined at some point during the process. To do this, you need to provide one of following pieces of information in order to identify that user:

  • The User's ID number, stored in a User ID Data Item

  • The User's username

  • The User's email address

If you can provide any of those three pieces of information to the Get User Profile activity, it can allow you to retrieve any other piece of information from the User's profile (such as the User's manager, or Instant Messenger screen name).

To retrieve information from a specific User's Profile

  1. Add the Get User Profile activity to the Canvas and complete the common activity properties.

    Note:
    Completing the common activity properties is essential to create an organized and functional process.

  2. Click the Get User Profile tab.

  3. Click the User Source drop-down list and select one of the following options, depending on which piece of information you're able to provide:

    • Data Item with UserID

    • Data Item with Username

    • Data Item with Email Address

  4. Click the Data Item drop-down list and select the Data Item that contains the information you chose with the User Source drop-down list. For example, if you chose Data Item with Username, then you should select the Data Item that will contain the User's username.

    Note
    If you selected Data Item with UserID, the Data Item that contains that ID number needs to be a UserID Data Item.

  5. Click the drop-down list in the Profile Attribute column, and select the User Profile attribute that you want to retrieve.

  6. Click the drop-down list in the Data Item column.
    The data type of the Profile attribute you picked in step 4 appears in the Data Type column.

  7. Use the Data Item drop-down list to select the Data Item that you want to hold the information you retrieve from the User Profile.

    Note
    The Data Type of the Data Item you choose must match the Data Type of the Profile attribute that you are retrieving. Otherwise, the Data Item will not appear in the drop-down list.

    Example
    If you want to retrieve a User's email address, which has a Data Type of "Text", then the Data Item you use should also have a Data Type of "Text".

  8. Optional: To retrieve more profile attributes, repeat steps 5-7 in a new row for every profile attribute you want to retrieve.

  9. Click OK.
    T    he Properties window closes.

When the activity executes, it will assign the User Profile attributes that you chose to the corresponding Data Items.

Related Topics

About the Get User Profile Activity | Retrieve Information from the Process Initiator's Profile | Retrieve Information from the Process Owner's Profile


Retrieve Information from the Process Initiator's Profile

You can use the Get User Profile activity to retrieve information from the User who started the process, known as the Process Initiator.

To retrieve information from the Process Initiator's Profile

  1. Add the Get User Profile activity to the Canvas and complete the common activity properties.

    Note:
    Completing the common activity properties is essential to create an organized and functional process.

  2. Click the Get User Profile tab.

  3. Click the left drop-down list under User Selection and select Initiator.

  4. Click the drop-down list in the Profile Attribute column, and select the User Profile attribute that you want to retrieve.

  5. Click the drop-down list in the Data Item column.
    The data type of the Profile attribute you picked in step 4 appears in the Data Type column.

  6. Use the Data Item drop-down list to select the Data Item that you want to hold the information you retrieve from the User Profile.

    Note:
    The Data Type of the Data Item you choose must match the Data Type of the Profile attribute that you are retrieving. Otherwise, the Data Item will not appear in the drop-down list.

    Example:
    If you want to retrieve a User's email address, which has a Data Type of "text", then the Data Item you use should also have a Data Type of "text".

  7. Optional: To retrieve more profile attributes, repeat steps 4-6 in a new row for every profile attribute you want to retrieve.

  8. Click OK to close the Properties window.

When the activity executes, it will assign the User Profile attributes that you chose to the corresponding Data Items.


Retrieve Information from the Process Owner's Profile

You can use the Get User Profile activity to retrieve information from the User who is responsible to maintain the process, known as the Process Owner.

To retrieve information from the Process Owner's Profile

  1. Add the Get User Profile activity to the Canvas and complete the common activity properties.

    Note:
    Completing the common activity properties is essential to create an organized and functional process.

  2. Click the Get User Profile tab.

  3. Click the left drop-down list under User Selection and select Owner.

  4. Click the drop-down list in the Profile Attribute column, and select the User Profile attribute that you want to retrieve.

  5. Click the drop-down list in the Data Item column.
    The data type of the Profile attribute you picked in step 4 appears in the Data Type column.

  6. Use the Data Item drop-down list to select the Data Item that you want to hold the information you retrieve from the User Profile.

    Note:
    The Data Type of the Data Item you choose must match the Data Type of the Profile attribute that you are retrieving. Otherwise, the Data Item will not appear in the drop-down list.

    Example:
    If you want to retrieve a User's email address, which has a Data Type of "text", then the Data Item you use should also have a Data Type of "text".

  7. Optional: To retrieve more profile attributes, repeat steps 4-6 in a new row for every profile attribute you want to retrieve.

  8. Click OK to close the Properties window.

When the activity executes, it will assign the User Profile attributes that you chose to the corresponding Data Items.


About the InRule Activity

The InRule activity is very similar to the Logical Expression Rules activity because it allows you to evaluate information stored in Data Items against a specific set of logical expressions. After you evaluate it, you can then rewrite that information to new Data Items.

However, while the Logical Expressions Rules activity requires you to create the logical expressions in BPM Designer, the InRule activity references an InRule logical expression repository which stores preexisting rules that are specific to your organization. The logical expression rules in the InRule repository can be much larger and more complicated than the rules in the Logical Expression Rules activity.

InRule uses Rule Apps (short for "rule applications") to evaluate business rules, which are data structures that store related calculations and decision logic. When you use an InRule activity, you reference business rules contained in Rule Apps.

Note:
You must have InRule 2.7 or greater installed on your BPM Server in order to use the BPM Suite InRule activity.

Prerequisites

Before you use the InRule activity, you should complete the following topics to enable all of InRule's functionality in your unique BPM Suite environment.

  • Defining your Default InRule Repository Connection Settings

  • Defining the Path to irAuthor

  • Opening irAuthor from BPM Designer

Configuring the InRule Activity

The following topics detail how to configure the InRule activity.

  • Configuring the InRule Application Settings

  • Defining a Unique InRule Repository Connection

Required Auxiliary Topics

You will need Data Items to store information sent to or retrieved from the InRule Entity you select.

  • Creating Data Items


Configuring the InRule Application Settings

The InRule activity allows you to use business rules and notifications defined in an InRule Rule App file.

Note:
You must have InRule 2.7 or greater installed on your BPM Server in order to use the InRule activity.

Note:
When you save a process, a blank Rule App file is created to store InRule business rules used in the process; process data is synced with the Rule App file every time the process is saved. Also, the name of the created Rule App file is the same as the process name plus an "anti-collision' value (Example: processName.1, processName.2, processName.3, etc.)

To configure the InRule application settings

  1. Add the In Rule Activity to the Canvas and complete the common activity properties.

    Note:
    Completing common activity properties is essential to create an organized and functional process.

  2. Click the InRule tab.

  3. If necessary, define a unique InRule Repository connection.

  4. Click the Rule App drop-down list and select the InRule Rule App you want to use.

  5. Click the Entity drop-down list and select the Rule App's Entity you want to use.

  6. On the Fields (input) tab, select Data Items to populate the Entity fields.

  7. Click the Fields (output) tab and select Data Items to populate the Entity fields.

  8. If necessary, click the Fields (validations) tab and select the fields from the Entity, the corresponding IsValid Data Items, and the Message Data Items.

  9. If necessary, click the Notifications tab and select the Notification from the Entity, the corresponding IsActive Data Items, and the Message Data Items.

  10. Click OK to close the Properties window.


Defining a Unique InRule Repository Connection

BPM Suite uses a default InRule Repository connection to look for Rule Apps and Entities. However, you have the option to bypass the default connection and enter an Inrule Repository connection unique to each InRule activity that you configure.

Note:
You must have InRule 2.7 or greater installed on your BPM Server in order to use the BPM Suite InRule activity.

To Define a unique InRule Repository connection

  1. Add the InRule Activity to the Canvas and complete the common activity properties.

    Note:
    Completing common activity properties is essential to create an organized and functional process.

  2. Click the InRule tab.

  3. Click the Change button located under InRule Repository Settings.
    The InRule Repository Properties window appears.

  4. Enter a server location for the InRule repository in the Web Service field.

    Note:
    There will be a default server location in this field. Replace this location with the one you want the activity to reference.

  5. Enter the user name necessary to access InRule in the Login field.

    Note:
    By default, the user name is admin.

  6. Enter the password necessary to access InRule in the Password field.

    Note:
    By default, the password is password.

  7. Click the Test Connection button.
    If configured correctly, the InRule Connection [SUCCESS] window appears.

  8. Click OK to close the InRule Connection [SUCCESS] window.

  9. Click OK to close the InRule Repository Properties window.

The InRule repository connection is set and is unique to the activity.

Related Topics

About the InRule Activity | Defining your Default InRule Repository Connection Settings | Configuring the InRule Application Settings


About the Logical Expression Rules Activity

You can use the Logical Expressions Rules activity, and your business logic, to collect Data Item values, evaluate selected values against a set of rules you define, and populate the new values into Data Items.

Logical Expressions Rules activities use logical expression strings to return either a True or False value. You can define additional values to return with a True and False values.

Example:

You need to create an activity that checks to see if a monthly budget statement is under $10,000. First, you store the value $10,000 in a Data Item named MonthlyBudget, which becomes a logical expression key. You then use the Logical Expression Rules activity to check the logical expression key against a rule you create, like the following rule

%MonthlyBudget% < 10000

If the budget amount is less than $10,000, then the logical expression will return a True value. If over, a False value. Using the "Return if..." fields in the Logical Expression window, you can then return a "Budget Rejected" value for a false value or a "Budget Approved" value for a true value. These values can be used for branching or display purposes later.

Setting the Logical Expression Keys to use with a Logical Expression Rules activity

When you configure a Logical Expression Rules activity, you will set the keys or rules at design time, by defining them within the activity, or at Run Time, by selecting Data Items that will hold the values. These rules must be defined before they can be used. The keys act as labels to help identify and organize the logical expressions.

  • Setting Logical Expression Keys at Design Time

  • Setting Logical Expression Keys at Run Time via Data Items

Working with Logical Expressions

If the logical expressions you need do not exist when you configure the Logical Expression Rules activity, you can create new ones without closing the Properties window. The topics below will help you write a new logical expression rule.

  • Understanding the Logical Expression Builder Toolbar

  • Writing a Logical Expression

  • Editing Logical Expressions

  • Testing a Logical Expression

Required Auxiliary Topics

Before you configure a Logical Expression Rules activity, create Data Items that will store the True/False value returned by the activity and the data values that you want to return for either the true or false value. Also, if you are setting the keys at Run Time, you will need up to three Data Items to hold the key or keys to use.

  • Creating Data Items


Editing Logical Expressions

Editing a Logical Expression

You can edit the logical expressions that you use to collect data and to drive your business logic.

To edit a logical expression

  1. From the Process Management menu, select Edit Logical Expressions.
    The Logical Expressions window appears.

  2. Use one of the following to locate your expression:

    • To see all expressions, select the Show All option.

    • To see only selected expressions, select the Filter By Key option and select the keys to use as filters.

  3. Click the Load Expressions button.
    The expressions load and populate the table.

  4. Edit the necessary cells.

    • For a cell with a blinking cursor, enter information directly into the cell.

    • For the Logical Expression cell, click the ellipses button to open the Logical Expression window. In this window, you can directly edit the logical expression.
      Tips for writing logical expressions      . When you have finished editing the logical expression, click OK to close the Logical Expression window.

  5. Click the Save Expression button to save your edits.

Related topics

About the Logical Expression Rules Activity


Setting Logical Expression Keys at Design Time

Logical expression keys represent labels for existing logical expression groups; each key points to a specific logical expression grouping and each successive key represents a more specific group of logical expressions. Set logical expression keys at design time to select the specific logical expression rule(s) group(s) that you want to use to evaluate Data Item values in the Logical Expression Rules activity.

If the required logical expression rules do not exist, you can write a new logical expression while setting the logical expression keys at design time.

Note:

Logical expressions return only true or false values, but they can also assign values to Data Items based upon the returned true or false value.

To set logical expression keys at design time

  1. Add the Logical Expression Rules activity to the Canvas and complete the common activity properties.

    Note:
    Completing common activity properties is essential to create an organized and functional process.

  2. Click the Logical Expressions Rules tab.

  3. Click the Set Keys at Design Time option.
    A group box called Use these Keys to choose Set of Rules allows you to set those keys.

  4. Click the Key 1 drop-down list and select the first key (logical expression grouping).

  5. If you need to set a more specific logical expression grouping, click the Key 2 drop-down list and select the second key.

  6. If you need to set a more specific logical expression grouping, click the Key 3 drop-down list and select the third key.

  7. Determine whether the expression in each group will use AND or OR logic:

    • Click the AND option if all expressions in the most specific group you will define need to be true.

    • Click the OR option if only one expression in the most specific group you define needs to be true.

Note:
The AND / OR logics apply to the last Key that you set. If you set up to Key 3, then the And / OR logics only apply to the logical expression in the Key 3 grouping. If you only set Key 1, then the AND / OR logics apply to all logical expressions in the Key 1 grouping.

  8. To reuse the default Data Item value, un-check the Do Not Reuse the Default DataItemValue check box.

  9. Click the Data Item to hold the Expression Result drop-down list and select the Data Item that will hold the actual true or false value(s) the expression results return.

  10. Click the Data Item to hold the Expression Data drop-down list and select the Data Item that will hold the assigned Data Item values based upon the returned true or false expression results.

  11. Click OK to close the Properties window.

When the activity runs, it will use the logical expression that you defined above.

Related Topics

About the Logical Expression Rules Activity


Setting Logical Expression Keys at Run Time

Logical expression keys represent labels for logical expression groups; each key points to a specific logical expression grouping and each successive key represents a more specific group of logical expressions.

When you want to use an existing logical expression in a Logical Expressions Rules activity, then you need to select the expression using the keys. If you do not set the logical expression key(s) at design time, you can set the keys using Data Items that hold logical expression keys, which will then specify the logical expression when the activity runs.

Note:

You cannot edit a logical expression when setting its keys at run time. Therefore, you must ensure that the Data Items you use to set the keys point to a complete and functional logical expression.

To set logical expression keys at run time

  1. Add the Logical Expression Rules activity to the Canvas and complete the common activity properties.

    Note:
    Completing common activity properties is essential to create an organized and functional process.

  2. Click the Logical Expressions Rules tab.

  3. Click the Set Keys at Run Time option.
    A group box called Pull Keys from These Data Items allows you to select Data Items that will define the keys.

  4. Click the Data Item for Key 1 drop-down list and select the first Data Item (that holds the first Key for a logical expression).

  5. If you need to set a more specific logical expression grouping, click the Data Item for Key 2 drop-down list and select the Data Item that holds the second Key for a logical expression.

  6. If you need to set a more specific logical expression grouping, click the Data Item for Key 3 drop-down list and select the Data Item that holds the third Key for a logical expression.

  7. Determine whether the expression in each group will use AND or OR logic:

    • Click the AND option if all expressions in the most specific group you will define need to be true.

    • Click the OR option if only one expression in the most specific group you define needs to be true.

Note:
The AND / OR logics apply to the last Key that you set. If you set a Data Item up to Key 3, then the AND / OR logics only apply to the logical expression in the Key 3 grouping. If you only set a Data Item for Key 1, then the AND / OR logics apply to all logical expressions in the Key 1 grouping.

  8. To reuse the default Data Item value, un-check the Do Not Reuse the Default Data ItemValue check box.

  9. Click the Data Item to Hold the Expression Result drop-down list and select the Data Item that will hold the actual true or false value(s) the expression results return.

  10. Click the Data Item to Hold the Expression Data drop-down list and select the Data Item that will hold the assigned Data Item values based upon the returned true or false expression results.

  11. Click OK to close the Properties window.

Related Topics

About the Logical Expression Rules Activity


Testing a Logical Expression

Before you use a logical expression in a process, you can test it to make sure that it returns the expected true and false values for all variables that it uses.

To test a logical expression

  1. Open the Properties window for the Logical Expression Rules activity.

  2. Open the Logical Expressions window, load all existing expressions, and open the Logical Expression editor window for the expression that you want to test.

    Note:
    If there are no existing expressions to test, then you can write an expression and then test it.

  3. Click the Parse Expression button.
    The table in the Populate Variables to Test Expression pane is filled with all available variables in the logical expression.

  4. In the empty field to the right of each variable, enter a variable to use to test the expression.

  5. Click the Test Expression button.
    The test results for logical expression appear in the Expression Results pane.

  6. Review the test results to see if the logical expression will return the expected true and false values.

  7. Click OK to close the Logical Expression window.

Related Topics

About the Logical Expression Rules Activity


Tips for Writing Logical Expressions

Below are tips that can help you write and edit logical expressions:

  • Accessing the Logical Expression window

  • Writing and testing logical expressions

To access the Logical Expression window

  1. From the Logical Expressions Rules tab, click the View/Input Rules button.
    The Logical Expressions window opens.

  2. Click a field in the Logical Expression column, and then click the ellipses button.
    The Logical Expression window opens.

  3. Use the table below to help you understand the buttons on the Expression Builder Toolbar.

Button | Description
+ - / = | Arithmetic functions.
<string literal> | Alphanumeric text that does not include numbers used in calculations. Clicking this button opens the String Literal window. In the String Literal window, you can enter string literals.
= | Equal to
<> | Not equal to
> | Greater than
< | Less than
>= | Greater than or equal to
<= | Less than or equal to
AND OR NOT | And, Or, and Not
() | Parentheses
Parse Expression | This button looks for possible Data Items in the expressions and puts them into the Populate Variable to Test Expression array.
Test Expression | This button tests the logical expression.
Common Function | Description
LEN("%DataItem%") | Returns the length of the value/display value contained in a Data Item. Can be used to see if a Data Item contains a value. Tip: In case the value is not a string, place quotes around the Data Item, so when processed it always acts like a string.

  4. Click OK.
    The Logical Expression window closes.

To write and test a logical expression

  1. Click the Expression Editor pane.
    The editor pane is below the Expression Builder toolbar.

  2. Create a the logical expression using Data Items, string literals, and the buttons on the Expression Builder toolbar as necessary.

  3. Click the Parse Expression button.
    The Data Items you used in the expression will appear in the Populate Variable to Test Expression array.

    Note:
    Before you can test an expression, you must enter values for the Data Item first.

  4. Click the Test Expression button.
    The test results appear in the Expression Results pane.

  5. Check the results of the expression to make sure the expression works correctly.

    • If the expression works correctly, click OK.

    • If the expression works incorrectly, edit the expression and retest.


Understanding the Logical Expression Builder Toolbar

BPM Designer gives you a set of tools to help build logical expression rules. Use the table below to familiarize yourself with the BPM Designer Logical Expression Builder Toolbar.

Button | Description
+ - / = | Arithmetic functions
<string literal> | Alphanumeric text that does not include numbers used in calculations. Clicking this button opens the String Literal window. In the String Literal window, you can enter string literals.
= | Equal to
<> | Not equal to
> | Greater than
< | Less than
>= | Greater than or equal to
<= | Less than or equal to
AND OR NOT | logical statements AND, OR, and NOT
() | Parentheses
Parse Expression | This button looks for Data Items in the expression and puts them into the Populate Variable to Test Expression array.
Test Expression | This button tests the logical expression.
Common Function | Description
LEN("%DataItem%") | Returns the length of the value/display value contained in a Data Item. Can be used to see if a Data Item contains a value. Tip: In case the value is not a string, place quotes around the Data Item, so when processed it always acts like a string.

Related topics

About the Logical Expression Rules Activity


Writing a Logical Expression

You can write your own logical expression if no existing logical expression meets your needs.

Note:
Logical expressions can only return either a true or false value. However, you can set values to return for both the true and false value returned by the logical expression.

To write a logical expression

  1. Add the Logical Expression Rules activity to the Canvas and complete the common activity properties.

    Note:
    Completing common activity properties is essential to create an organized and functional process.

  2. Click the View/Input Rules button.
    The Logical Expressions window appears.

  3. Click the lowest empty field under the Key 1 column.

  4. Enter a name for the Key 1 value of the logical expression.
    An additional row appears under the row you are typing in. This row is for any additional logical expressions that you may add.

  5. Repeat steps 3 and 4 to enter a name for Key 2 and Key 3 under their respective columns.

    Note:
    Create descriptive Logical Expression Keys so that you can easily reference the logical expression in the future.

  6. Click the empty field under the Logical Expression column.
    An ellipses button appears in the field.

  7. Click the Ellipses button [image].
    The Logical Expression window appears.

  8. Create a logical expression using Data Items, string literals, and the buttons on the Expression Builder toolbar as necessary.

    Note:
    As a rule, do not use a question mark (?) to build an expression.

  9. Test the logical expression.

  10. Click OK to close the Logical Expression window.

  11. Enter the value you want the logical expression to return if it is true in the Return Value if True field.

    Note:
    You do not have to enter a value in this field if it is not required.

  12. Enter the value you want the logical expression to return if it is false in the Return Value if False field.

    Note:
    You do not have to enter a value in this field if it is not required.

  13. Click the Save Expressions button.
    The logical expression is saved. You can now use it in a process or a Logical Expression Rules activity.

Related Topics

About the Logical Expression Rules Activity


About the CRM Activity

About the Microsoft CRM 1.2 Activity

You can use the Microsoft CRM 1.2 activity to create, remove, update, and delete "entities" in Microsoft CRM. In Microsoft CRM, almost everything (e.g. accounts, leads, quotes, and products) is an "entity".

Follow the links below to learn how to configure a CRM activity.

  • Configuring the CRM Server Settings

  • Creating a New CRM Entity

  • Retrieving an Existing CRM Entity

  • Updating a CRM Entity

  • Deleting a CRM Entity

Required Auxiliary Topics

You will need to create Data Items for almost every piece of information you put into or retrieve from the CRM server. It is a good idea to think about what Data Items might be necessary before you create the activity, then create those Data Items.

  • Creating Data Items


Configuring the CRM Server Settings

Before you can configure the CRM activity to do anything, you should set up a connection to the CRM server. After you set up a connection in one CRM activity, every other CRM activity will be set to the same connection.

To set up a connection to the CRM server

  1. Add the CRM activity to the Canvas and complete the common activity properties.

    Note:
    Completing common activity properties is essential to creating an organized and functional process.

  2. Click the CRM tab. The upper section contains CRM server settings.

  3. Click Change Settings. The CRM Server Settings window appears.

  4. Enter the virtual directory address of the CRM server in the CRM Server Vir Dir field.

  5. Enter your CRM login in the Login field.

    Note:
    Your login should be in the format Domain\Login.

  6. Enter your CRM password in the Password field.

  7. Click Test Connection. If the connection is valid, a window confirms the connection. If the connection fails, make sure you entered the correct information.

  8. Click OK to close the CRM Server Settings window.

Related Topics

About the CRM Activity.


Creating a New CRM Entity

You can use the Create New CRM Entity function of the Microsoft CRM activity to create a new entity in Microsoft CRM.

To create a new CRM entity in Microsoft CRM

  1. Add the CRM activity to the Canvas and complete the common activity properties.

    Note:
    Completing common activity properties is essential to creating an organized and functional process.

  2. Click the CRM tab. The lower section contains options for how to communicate with the CRM server.

  3. C onfigure CRM Server Settings, if you have not already done so.

  4. Click the CRM Operation drop-down list and select Create New CRM Entity.

  5. Click the CRM Entity drop-down list and select the type of entity you want to create. The grid at the bottom of the tab populates with a list of every field you can complete for that entity.

  6. Click the Entity Key drop-down list and select the Data Item that you want to hold the GUID (unique identifier) for this CRM entity.

    Note:
    You can choose no Data Item for the Entity Key, but then you will not be able to access that same entity from within the Designer later.

  7. Map CRM Field Names to Values. You can enter a value by hand or you can click the ellipsis button to map the field to a Data Item that will contain the value at run-time.

    Note:
    The Type column tells you what sort of entry Microsoft CRM expects to receive. If the Type is a picklist, you can click the ellipsis button under the Value column to see the list options. The Required column tells you which fields must contain a value for the activity to complete successfully.

  8. Click OK after you have created all the necessary mappings between CRM fields and values.

Related Topics

About the CRM Activity | Configure the CRM Server Settings.


Deleting an Existing CRM Entity

You can use the Delete CRM Entity function of the Microsoft CRM activity to update information in an entity in Microsoft CRM.

To update information from an entity in Microsoft CRM

  1. Add the CRM activity to the Canvas and complete the common activity properties.

    Note:
    Completing common activity properties is essential to creating an organized and functional process.

  2. Click the CRM tab. The lower section contains options for how to communicate with the CRM server.

  3. C onfigure CRM Server Settings, if you have not already done so.

  4. Click the CRM Operation drop-down list and select Delete CRM Entity.

  5. Click the CRM Entity drop-down list and select the type of entity you want to delete.

  6. Click the ellipsis button next to the Entity Key field and select the Data Item that holds the GUID (unique identifier) of the CRM entity you want to delete.

  7. Click OK to close the Microsoft CRM activity.

Related Topics

About the CRM Activity | Configure the CRM Server Settings.


Retrieving an Existing CRM Entity

Retrieving a CRM Entity

You can use the Retrieve CRM Entity function of the Microsoft CRM activity to retrieve information from an entity in Microsoft CRM.

To retrieve information from an entity in Microsoft CRM

  1. Add the CRM activity to the Canvas and complete the common activity properties.

    Note:
    Completing common activity properties is essential to creating an organized and functional process.

  2. Click the CRM tab. The lower section contains options for how to communicate with the CRM server.

  3. C onfigure CRM Server Settings, if you have not already done so.

  4. Click the CRM Operation drop-down list and select Retrieve CRM Entity.

  5. Click the CRM Entity drop-down list and select the type of entity you want to retrieve. The grid at the bottom of the tab populates with a list of every field from which you can retrieve information.

  6. Click the ellipsis button next to the Entity Key field and select the Data Item that holds the GUID (unique identifier) of the CRM entity you want to retrieve.

  7. Map CRM Field Names to Values. Click a field under the Data Item column to reveal a drop-down list. Select the Data Item that you want to contain the CRM entity from that drop-down list.

  8. Click OK after you have created all the necessary mappings between CRM fields and Data Items.


Updating an Existing CRM Entity

You can use the Update an Existing CRM Entity function of the Microsoft CRM activity to update information in an entity in Microsoft CRM.

To update information from an entity in Microsoft CRM

  1. Add the CRM activity to the Canvas and complete the common activity properties.

    Note:
    Completing common activity properties is essential to creating an organized and functional process.

  2. Click the CRM tab. The lower section contains options for how to communicate with the CRM server.

  3. C onfigure CRM Server Settings, if you have not already done so.

  4. Click the CRM Operation drop-down list and select Update Existing CRM Entity.

  5. Click the CRM Entity drop-down list and select the type of entity you want to retrieve. The grid at the bottom of the tab populates with a list of every field in which you can update information.

  6. Click the ellipsis button next to the Entity Key field and select the Data Item that holds the GUID (unique identifier) of the CRM entity you want to retrieve.

  7. Map CRM Field Names to Values. Click a field under the Data Item column to reveal an ellipsis button. Click the ellipsis button to enter a value or select a Data Item that you want to populate that CRM field.

    Note:
    The Type column tells you what sort of entry Microsoft CRM expects to receive. If the Type is a picklist, you can click the ellipsis button under the Value column to see the list options.

  8. Click OK after you have created all the necessary mappings between CRM fields and Data Items.


About the MSMQ Reader Activity

About MSMQ Reader Activity

You can use the MSMQ Reader activity to listen for a message or messages to arrive in a message queue that meet specific criteria. Information from messages matching those criteria can be written to Data Items to be used later in the process.

Use the links below to see the steps required to filter and write information from MSMQ messages.

Automatically Populating Data Items from a Message Queue

To automatically populate Data Items from a Message Queue, you must first configure the MSMQ reader with the queue location

  • Configuring the MSMQ Reader

  • Creating Message Filters

  • Mapping Data Items

Required Auxiliary Topics

To successfully configure a MSMQ Reader activity, you need to create Data Items that store the information from the message queue.

  • Creating Data Items


Configuring the MSMQ Reader

Configuring the MSMQ Message Reader

Before you can populate Data Items, you must configure the common activity properties and the queue location of the MSMQ reader.

To Configure the MSMQ Reader

  1. Add the MSMQ Reader activity to the designer canvas and complete the common activity properties.

  2. Click the Message Queue tab.

  3. Select the Message Queue box to enter the location and name of queue you wish to monitor for messages.
    Optionally, to use Data Item values in the queue name:

    1. Click the Edit button.
      The Input Queue Name window appears.

    2. If you want to include Data Item values in the message queue name, select a Data Item in the Available Data Items list and click Insert Display Value or Insert Value.

      Note:
      There may be a difference between the Value and the Display Value of a Data Item.

    3. Optionally, click the Preview Queue Name button to see how the queue name you have entered will appear.

    4. Click OK.
      The Input Queue Name window will close.

Note:
At run-time, if this message queue cannot be found, then the activity will fail and the log should record the error as the message queue could not be found.

Related Topics
Creating Message Filters, Mapping Data Items, About MSMQ Reader Activity


Creating Message Filters

To obtain information from messages, you must create filters by which to search for the information you want to write to a Data Item.

To Create Message Filters

  1. To create a new Message Attribute filter, click the Message Attribute field in the bottom, empty row in the Message Filters grid and select the attribute by which you would like to filter messages.

  2. Select one of the following sources from the Source drop-down list:

    • Constant

    • DataItem.DisplayValue

    • DataItem.Value

  3. Enter the value of the header into the Value field

    • If you specified the source as a constant, enter a static value into the Value field.

    • If you chose a DataItem.DisplayValue or a DataItem.Value, select the DataItem you wish to use from the Value drop-down list.

      Note:
      At run-time, the log should record the before and after path showing how Data Item tokens were replaced.

  4. Repeat steps 1-4 for each attribute you wish to filter.

Note:
At run-time, the value of the Data Item is used as the filter. The Data Item value can contain a regular expression (Example: message* could match messages, message received, message available, etc.)

  5. Enter how long you want to wait for this activity to arrive using one of the following methods:

    • Select a Data Item from the Select Data Item drop-down list.

    • Enter a static value into the Enter time box.

  6. Optionally, if you wish to forward the messages received by this queue to another queue, select the Forward message to queue box and enter the location and name of the message queue you wish to forward the messages to into the Message queue box.

Related Topics

Configuring the MSMQ Reader, Mapping Data Items, About MSMQ Reader Activity


Mapping Data Items

  1. Click the Ellipsis button to the right of the File Name cell.
    The Configure Output File Name window appears.

  2. If necessary, select Data Items from the Available Data Items list and click the Insert Display Value or Insert Value button to add the Data Item value to the File name field.

  3. If necessary, select other variables from the Available Non-Data Items list and click the Insert button to add the value to the File name field.

  4. The File name field shows the final file name with placeholders for all the variables.

  5. Click the Preview File Name button to enter values for the variables and see what the final file name might look like.

  6. Click OK when you're done creating the output file name.

  7. The file name appears in the Output file name field.

Mapping Information to Data Items

Finally, you must map the information you retrieve from the messages to the Data Items you wish to store them in.

To Map Information to Data Items

  1. Click the Data Mapping tab.

  2. Enter the Data Items in which you wish to store information from the response headers into the Response Header grid.

    1. To add a Data Item to the grid, select it from the Data Item drop-down list in the Response Header grid.

    2. Select the attribute you wish to store from the Source drop-down list.

    3. If you would like to clear any existing information in the Data Item before writing the attribute value, select the Clear Existing Value box.

    4. If the Data Item that you added is a FilePointer Data Item, Perform one of the following actions to define the output file name:

      • Enter the output file name in the Output file name field

      • Build an output file name that uses variables

        Note:
        Be sure to enter the file extension (example: .txt, .xml) at the end of the file name.

    5. Repeat steps 1 - 4 for every response header you wish to store.

Related Topics

Configuring the MSMQ Reader, Creating Message Filters, About MSMQ Reader Activity


About the MSMQ Writer Activity

About MSMQ Writer Activity

You can use the MSMQ Writer activity to write text or XML contained within a data Item or file referenced by a FilePointer Data Item to a Microsoft Message Queue.

Use the links below to see the steps required to write information from MSMQ messages

  • Configuring the MSMQ Writer

  • Mapping Data Items

Required Auxiliary Topics

To successfully configure a MSMQ Writer activity, you need to create Data Items that store the information that will be contained in the message.

  • Creating Data Items


Configuring the MSMQ Writer

Before you can populate Data Items, you must configure MSMQ reader properties and message options.

To Configure the MSMQ Writer

  1. Add the MSMQ Writer activity to the designer canvas and complete the common activity properties.

  2. Click the Message Queue tab.

  3. Select the Queue box to enter the location and name of queue you wish to send messages.
    Optionally, to use Data Item values in the queue name:

    1. Click the Edit button.
      The Input Queue Name window appears.

    2. If you want to include Data Item values in the message queue name, select a Data Item in the Available Data Items list and click Insert Display Value or Insert Value.

      Note:
      There may be a difference between the Value and the Display Value of a Data Item.

    3. Optionally, click the Preview Queue Name button to see how the queue name you have entered will appear.

    4. Click OK.
      The Input Queue Name window will close.

Note:
At run-time, if this message queue cannot be found, then the activity will fail and the log should record the error as the message queue could not be found.

To Specify the Message Options

Refer to the chart below to select the options you wish to utilize in your message.

Option | Description
Recoverable | When selected, the message queue guarantees that the message will be delivered in case of a computer or network problem.
Use dead letter queue | When selected, a copy of messages that cannot be delivered will be sent to the dead-letter queue
Use encryption | Gets or sets a value that indicates whether to make the message private.
Use tracing | When selected, the message is traced as it moves toward the destination queue.
Use journal queue | When selected, a copy of the message is kept in a journal queue on the computer that created the message.

Related Topics
Mapping Data Items, About the MSMQ Writer Activity


Mapping Data Items

Mapping Information to Data Items

Finally, you must map the information you retrieve from the messages to the Data Items you wish to store them in.

To Map Information to Data Items

  1. Click the Data Item Mapping tab.

  2. Enter the Data Items in which you wish to store information from the response headers into the Response Header grid.

    1. To add a Message Attribute to the grid, select a message attribute from the Message Attribute drop-down list in the Mapping grid.

    2. Select the location from which you wish to read the attribute's value from the Source drop-down list.

      • If you selected Constant for the source, enter a static value into the Value field.

      • If you selected DataItem.DisplayValue or DataItem.Value for the source, select the Data Item whose value you wish to send in the message from the Value drop-down list

    3. Repeat steps 1 - 4 for every response header you wish to store.

Related Topics

About MSMQ Writer Activity, Configuring the MSMQ Writer


About the Multi-instance Sub-Process Activity

You can use the Multi-instance Sub-Process activity to start multiple versions of the same sub (child) process from a single step in the main (parent) process.

To start multiple versions of the same child process, you need to create a Data Item that holds values which, when used in the Multi-Instance Sub Process activity, will act as a counter (or Key) for the number of processes to start (one per key).

Example:
If the counter Data Item holds five values (when a Data Item holds multiple values, each value is referred to as an instance), the Multi-Instance Sub Process activity will start five versions of the same process, relative to each value.

Required Auxiliary Activities

In order to start multiple processes, either a Logical Expression activity or a Table Reader activity must come before the Multi-instance Sub-Process activity. Logical Expression and Table Reader activities are able to populate that single Data Item with multiple values.

Creating Multi-instance Sub-Process Types

You can create two types of Multi-instance sub-processes:

  1. Synchronous Multi-instance sub-processes are a group of child processes that must complete before the parent process can continue.

  2. Asynchronous Multi-instance sub-processes are a group of child processes that allow the parent process to continue while the child processes run.

  • Creating a Synchronous Multi-instance Sub-Process

  • Creating an Asynchronous Multi-instance Sub-Process

  • Controlling the Number of Processes a Multi-Instance Sub-Process Starts

Mapping Data Items to a Multi-Instance Sub Process

  • Mapping Individual Data Items to a Multi-instance Sub-Process

  • Mapping Selected Data Item Groups to a Multi-instance Sub-Process

  • Auto-Mapping Similar Data Items Between Processes

Mapping Multi-instance Sub-Process Data Item so they Rewrite Main Process Data Items

  • Mapping Writable Multi-instance Sub-Process Data Items

  • Allowing Mapped Multi-instance Sub-Process Data Items to be Writable


Allowing Mapped MI SP DIs to be Writable

This Writable Data Item mapping will allow the last Multi-Instance sub process to execute to rewrite the value of the Data Item and reenter it into the parent process.

This Writable Data Item will only rewrite back to the parent process the values of Data Items that have changed, relative to the original value that the parent process mapped to all instances of the sub process.

This Writable Data Item will delete all values stored in the mapped parent process Data Items and then replace them when the Multi-Instance sub process executes.

This Writable Data Item will create additional instances of a Data Item's value(s).

Example:
If a Data Item has three original values, it will have six (three original / three new) values after the sub processes execute if the mapped Data Items are Write Back Preserve Parent Values.

Allowing Mapped Multi-instance Sub-Process Data Items to be Writable

You can allow mapped Multi-Instance sub-process Data Items to be writable, which will cause the sub-process to rewrite Data Items and then enter the new values back into to the main process. Below, you will learn how to make Data Items that have already been mapped writable.

To allow mapped Multi-Instance sub process Data Items to be writable

  1. Create either a synchronous or asynchronous sub-process.

  2. Click the Edit Data Mappings button.
    The Map Data Items between the Main Process and Sub Process window appears.

  3. If required, map the Data Items using a one of the following methods:

    • Map Individual Data Items to a Sub-Process

    • Map Selected Data Item Groups to a Sub-Process

    • Auto-Map Similar Data Items

  4. In the Data Mapping Options between Processes table, click the multi-instance sub-process Data Item that you want to use to rewrite the main process Data Item when the Multi-Instance sub process executes.
    The Data Item's row is highlighted.

  5. Click the Write Back Option drop-down list at the bottom of the window and select one of the following options.

  • Write Back

  • Write Back Changes Only

  • Write Back Clear Parent Values

  • Write Back Preserve Parent Values

  5. Click Close.

  6. Click OK to close the Properties window.

The Multi-instance sub-process Data Item will rewrite the value of the main process Data Item once the Multi-instance sub-process runs.

Related Topics

About the Multi-instance Sub-Process Activity


Auto-Mapping Similar DIs between Procs

Auto-Mapping Similar Data Items Between Processes

You can use this method if you want BPM Suite to automatically map all the Data Items with the same names between processes.

To auto-map similar Data Items between processes

  1. Create either a synchronous or asynchronous sub process.

  2. Click the Edit Data Mappings button.
    The Map Data Items between the Main Process and Sub Process window appears.

  3. Click the Map All button.
    The mapped Data Items appear in the Data mapping options between processes pane.

  4. Click Close.

  5. Click OK to close the Properties window.

All unreserved main process Data Items with the same name as sub-process Data Items are auto-mapped to the respective sub process Data Items.

Related Topics

About the Multi-Instance Sub Process Activity


Controlling the Number of Procs Started

Controlling the Number of Processes a Multi-Instance Sub Process Starts

By default, a Multi-instance Sub-Process activity launches a process for each value in a multiple value Data Item; however, you can limit the number of sub-processes the activity launches by using the Multi-instance Sub-Process activity's True/False Check.

A True/False Check reads the True/False values you associate with each value in a multiple value Data Item and starts a process for only each true instance value. This method allows you to control the number of processes a Multi-instance Sub-Process launches if you assign a True/False value to each Data Item value using a Logical Expression Rules activity.

Important

Before you configure a Multi-instance Sub-Process to use a True/False Check, you need to use a Logical Expression Rules activity to set multiple values for:

  • A multiple value Data Item key that the Multi-instance Sub-Process will use to start one process for each value instance in the Data Item

  • A True/False multiple value Data Item that associates either a True or False instance with one instance in the multiple value Data Item key.

True/False Check Example

The following table illustrates how data configured in an example Logical Expression Rules activity controls a True/False Check in a Multi-instance Sub-Process activity. In this example, a logical rule is used to determine which Users will be tasked with a document approval Multi-instance Sub-Process according to whether the document is an invoice or budget.

The left column represents the logical expression entered in order to receive either a True or False value. The middle column represents the True/False value returned if the document is an invoice. Finally, the last column represents the User who will be assigned a task in each launched Multi-instance Sub-Process, depending upon the document type entered.

Notice how %DocumentType.Value% represents one Data Item with multiple values.

Logical Expression Rules | UserToTask_TF True/False Value Returned | UserToTask Data Value Returned if True
%DocumentType.Value% = Invoice | True | 10
%DocumentType.Value% = Invoice | True | 32
%DocumentType.Value% = Invoice | True | 15
%DocumentType.Value% = Invoice | True | 2
%DocumentType.Value% = Budget | False | 6
%DocumentType.Value% = Budget | False | 20

The Multi-instance Sub-Process activity uses the True/False Check to start a sub-process for each True value returned by the logical expressions (stored in a True/False Data Item). In total, four Multi-instance Sub-Processes were started in this example. Conversely, if the document type was Budget, then the %DocumentType.Value% = Budget logical expressions would be true, and only two Multi-instance Sub-Processes would start.

To control the number of processes a Multi-Instance sub process starts

  1. Select a sub-process, synchronization option, and the Data Item to use as a key.

  2. Select the Use this Data Item as a True/False Check option.
    The drop-down list under the option becomes enabled.

  3. Click the Use this Data Item as a True/False Check drop-down list and select the Data Item that holds the multiple True/False values linked to the key Data Item values.
    The Multi-instance Sub-Process activity will start a process only for each value that checks as true.

  4. Click OK to close the Properties window.

Related Topics

About the Multi-instance Sub-Process Activity


Creating a Synchronous MI SP

Creating a Synchronous Multi-Instance Sub Process

You can use a synchronous Multi-instance sub-process when you want the main process to wait for all of the sub-processes in the activity to complete before the main process continues.

This Multi-instance sub-process type is ideal when the main process requires information produced by the sub-processes in order to continue.

To create a synchronous Multi-instance sub-process

  1. Add the Multi-instance Sub-Process activity to the Canvas and complete the common activity properties.

    Note:
    Completing common activity properties is essential to create an organized and functional process.

  2. Click the Multi-Instance Sub-Process tab.

  3. Click the ellipsis button next to the Select a Process as a Sub-Process field.
    The Select Subprocess window appears.

  4. Double-click the process you want to link as a sub-process.
    The process appears in the Select a Process as a Sub-Process field.

  5. Click the Data Item to use as Key drop-down list and select a Data Item that holds multiple values.

  6. Click the Synchronization options drop-down list and select (Synchronous) Synchronize with parent flow.

  7. Map Data Items from the parent process to the child processes using any of the following three methods:

    • Mapping Individual Data Items to a Multi-instance Sub-Process

    • Mapping Selected Data Item Groups to a Multi-instance Sub-Process

    • Auto-Mapping Similar Data Items Between Processes

Note:
If you want the Multi-instance sub-processes to write data back to the main process, map Writable Data Items.

  8. Click OK to close the Properties window.

When the activity runs, it will start a sub-process for each value in the Data Item you selected and it will require each sub-process to complete before the main process continues.

Related Topics

About the Multi-instance Sub-Process Activity


Creating an Asynchronous MI SP

Creating an Asynchronous Multi-Instance Sub Process

You can use an asynchronous Multi-instance sub-process when you want to allow the main process to continue while the sub-processes in the activity run.

To create an asynchronous Multi-instance sub-process

  1. Add the Multi-Instance Sub Process activity to the Canvas and complete the common activity properties.

    Note:
    Completing common activity properties is essential to create an organized and functional process.

  2. Click the Multi-Instance Sub-Process tab.

  3. Click the ellipsis button next to the Select a Process as a Sub-Process field.
    The Select Subprocess window appears.

  4. Double-click the process you want to link as a sub-process.
    The process appears in the Select a Process as a Sub-Process field.

  5. Click the Data Item to use as Key drop-down list and select a Data Item that holds multiple values.

  6. Click the Synchronization options drop-down list and select (Asynchronous) Do not synchronize with parent flow.
    A window notifies you of the Asynchronous option consequences.

  7. Click Yes.

  8. Map Data Items from the parent process to the child processes using any of the following three methods:

    • Mapping Individual Data Items to a Multi-instance Sub-Process

    • Mapping Selected Data Item Groups to a Multi-instance Sub-Process

    • Auto-Mapping Similar Data Items Between Processes

Note:
If you want the Multi-Instance sub processes to write data back to the main process, map Writable Data Items.

  9. Click OK to close the Properties for Activity window.

When the activity runs, it will start a sub-process for each value in the Data Item you selected and it will allow the parent process to continue before all of the sub-processes complete.

Related Topics

About the Multi-Instance Sub Process Activity


Mapping Individual DIs to a MI SP

Mapping Individual Data Items to a Multi-instance Sub-Process

You can use this Multi-instance sub-process Data Item mapping method if you want to map individual Data Items, one at a time.

Note:

You can only map global Data Items if BPM Suite does not use them to manage the process. Data Items like FlowDefID are "reserved" because every process (both main and sub) uses them to identify itself within BPM Suite.

To map individual Data Items to a Multi-Instance sub process

  1. Create either a synchronous or asynchronous sub process.

  2. Click the Edit Data Mappings button.
    The Map Data Items between the Main Process and Subprocess window appears.

  3. Select a Data Item in the Main Process pane that you want to map to a sub-process Data Item.

  4. Select a Data Item in the Subprocess pane that you want to map the main process Data Item.

  5. Click the Map button.
    Both Data Items appear in the Data mapping options between processes pane, under their respective columns.

  6. Repeat steps 3-5 to map additional individual Data Items.

  7. Click Close when you have finished mapping Data Items.

  8. Click OK to close the Properties window.

The Multi-instance Sub-Process Data Item(s) you selected receive the data stored by the main process data item(s) you selected.

Related Topics

About the Multi-instance Sub-Process Activity


Mapping Selected DIs to a MI SP

Mapping Selected Data Item Groups to a Multi-Instance Sub Process

You can use this Multi-instance sub-process Data Item mapping method if you want to map several Data Items with the same name between a main and multiple sub processes.

Note:
You cannot map reserved Data Items because only BPM Suite can change their value.

To map selected Data Item groups to a sub process

  1. Create either a synchronous or asynchronous sub-process.

  2. Click the Edit Data Mappings button.
    The Map Data Items between the Main Process and Subprocess window appears.

  3. Press and hold the Ctrl key on your keyboard.

    Note:
    Holding down the Ctrl key allows you to select multiple Data Items at once.

  4. While holding the Ctrl key, select the Data Items from the Main Process pane that you want to map to Multi-instance sub-process Data Items.
    The Map Selected button is enabled once you select more than one Data Item.

  5. When done selecting Data Items, release the Ctrl key and click the Map Selected button.
    The mapped Data Items appear in the Data mapping options between processes pane.

  6. Click Close.

  7. Click OK to close the Properties window.

The main process Data Items you selected are mapped to the respective Multi-Instance sub process Data Items with the same name.

Related Topics

About the Multi-Instance Sub Process Activity


Mapping Writable MI SP DIs

This Writable Data Item mapping will allow the last Multi-Instance sub process to execute to rewrite the value of the Data Item and reenter it into the parent process.

This Writable Data Item will only rewrite back to the parent process the values of Data Items that have changed, relative to the original value that the parent process mapped to all instances of the sub process.

This Writable Data Item will delete all values stored in the mapped parent process Data Items and then replace them when the Multi-Instance sub process executes.

This Writable Data Item will create additional instances of a Data Item's value(s).

Example:
If a Data Item has three original values, it will have six (three original / three new) values after the sub processes execute if the mapped Data Items are Write Back Preserve Parent Values.

Mapping Writable Multi-instance Sub-Process Data Items

You can map Writable Multi-instance Sub-Process Data Items to allow the Multi-instance Sub-Processes to rewrite Data Items and then enter the new values back into to the main process. Below, you will learn how to make Multi-instance sub-process Data Items writable as you map them.

To map writable Multi-Instance sub process Data Items

  1. Create either a synchronous or asynchronous sub-process.

  2. Click the Edit Data Mappings button.
    The Map Data Items between the Main Process and Sub Process window appears.

  3. Click the Write Back Option drop-down list and select one of the following choices.

  • Write Back

  • Write Back Changes Only

  • Write Back Clear Parent Values

  • Write Back Preserve Parent Values

  4. Map the Data Items using a one of the following methods:

    • Map Individual Data Items to a Sub-Process

    • Map Selected Data Item Groups to a Sub-Process

    • Auto-Map Similar Data Items

  5. Click Close.

  6. Click OK to close the Properties window.

The Multi-instance sub-process Data Items will rewrite the value of the main process Data Items once the Multi-instance sub-process runs.

Related Topics

About the Multi-instance Sub-Process Activity


About the Null Activity

The Null activity is a placeholder activity that may help you design processes. This activity has no executable functions and requires no configuration. Null activities complete as soon as they execute and continue the process automatically.

Use the Null activity to help you design a process before you insert and configure working activities. To help you plan a process as you design it using Null activities, you can make them look like the complete activities that you plan to replace them with when you configure the process at the activity level.

  • Using a Placeholder for an Activity


Using a Placeholder for an Activity

You can use the Null activity to create a placeholder that looks like the activity you will replace it with when you configure the process.

To use a placeholder for an activity

  1. Add the Null activity to the designer canvas and open the Properties for Activity window.

  2. Click the Display tab.

  3. Under Icon Properties, double-click the null activity icon.
    A window with a list of activity icons appears.

  4. Click the activity icon for which you want the Null activity to act as a placeholder.
    The activity icon's name appears in the File Name field.

  5. Click Open.
    The activity icon list window closes.

  6. Click OK.
    The Null activity icon looks like the activity for which you want it to act as a placeholder.

Related Topics

About the Null Activity


About the PDF Converter Activity

The PDF Converter activity uses a third-party tool called ActivePDF to convert documents to PDF format. ActivePDF can convert from over 280 file formats. Supported formats include: plain text, rich text, HTML, Microsoft Word, Microsoft Works, WordPerfect, Microsoft Excel, Microsoft PowerPoint, and most common image formats.

Before you can use the PDF Converter activity, you need to download and install ActivePDF Server and DocConverter. You can download a free 14 day trial or purchase a server license. For more information about ActivePDF, or to download the free trial, please visit http://www.activepdf.com.

Note
During the trial period, ActivePDF will add a watermark to any PDFs created with this activity.

Preparing to Use the PDF Converter Activity

  • Downloading and Installing ActivePDF

  • Selecting ActivePDF Working Directories

Using the PDF Converter Activity

  • Selecting the Input and PDF Output Files

  • Protecting the Output PDF with a Password

Required Auxiliary Topics

Before you begin configuring a PDF Converter activity, make sure to complete the following:

  • Create FilePointer Data Items to store the Input File and the PDF Output


Downloading and Installing ActivePDF

Before you can use the PDF Converter activity in BPM Suite, you need to install ActivePDF Server and ActivePDF DocConverter. For more information on ActivePDF Server and DocConverter, please visit the ActivePDF Web site.

ActivePDF Server and DocConverter can be installed on the same server that hosts BPM Suite or a different server. The PDF Converter activity uses these third-party tools to perform the actual PDF conversion.

Please refer to ActivePDF's documentation for assistance setting up ActivePDF Server and DocConverter.


Protecting the Output PDF with a Password

You can use the PDF Converter activity to apply a password to the output PDF file. If necessary, you can even apply two passwords to enable certain functions with one password and other functions with an auxiliary password.

To Protect the Output PDF with a Password

  1. If you have not already done so, select the Input and PDF Output files.

  2. Click the PDF Converter tab.

  3. Select the Use PDF Document Security option.

  4. Click the Main Password Data Item drop-down list and select the Data Item that will contain the password you want to apply to this PDF.

  5. Select any of the following options to prohibit PDF functions unless the user enters the password:

    • Open Document

    • Copy Text & Images to Clipboard

    • Print Document

    • Edit Document

    • Modify PDF Forms

  6. Optionally, select the Use separate password for printing, editing, & modifying option to enter an auxiliary password.
    If you enter an auxiliary password, a user will not be able to print, edit, or modify the output PDF without entering this password.

    Click the     Password Data Item drop-down list and select the Data Item that will contain the auxiliary password.

  7. Optionally, select the Enable 128-bit Security option to enhance the security level of the PDF password protection.

    Note
    If you do not select this option, the PDF will use 64-bit security.

  8. Click OK.
    The Properties window will close.


Selecting ActivePDF Working Directories

After you download and install ActivePDF, you need to select three working directories for ActivePDF. These three directories contain the temporary files, error log, and output files generated by ActivePDF.

To Select the ActivePDF Working Directories

  1. Create three directories in Windows to contain the ActivePDF working files.

    Note
    You can create these directories on the same server that hosts BPM Suite or a different server.

    Example
    C:\Program Files\Bluespring\PDF\Temporary\
    and
    C:\Program Files\Bluespring\PDF\Output\
    and
    C:\Program Files\Bluespring\PDF\Errors\

    You do not need to use the examples given here. The working file directories can be located anywhere that is accessible to ActivePDF.

  2. Open BPM Designer.

  3. Click Tools > Options.

  4. Click the ActivePDF Settings tab.

  5. Select the ActivePDF DocConverter Installed option.

  6. Indicate where ActivePDF is installed by performing one of the following actions:

    • If ActivePDF is installed on the same server, select the Server on same machine as BPM Engine option

    • If ActivePDF is installed on a different server, select the Server on different machine option and enter the IP address of that server in the IP box.

  7. Click the Temporary File Directory box and enter the path to the directory you created for ActivePDF's temporary files.

    Note
    If you created this directory on the same server as BPM Suite, then you can use local file paths (e.g. C:\Directory\). However, if you created this directory on a different server, you should provide the file path in UNC format (e.g. \\ServerName\Directory\). This applies for all three of the working directories.

  8. Click the PDF File Output Directory box and enter the path to the directory you created for ActivePDF's output files.

  9. Click the Error File Directory box and enter the path to the directory you created for ActivePDF's error log.

  10. Click OK.


Selecting the Input and PDF Output Files

You can use the PDF Converter activity to convert most kinds of document into PDF documents. The original document will remain unchanged and a PDF copy of the file will be created and placed in a FilePointer Data Item. If you have not already done so, you need to create at least two FilePointer Data Items in this process: one to contain the input file and one to contain the output file.

To Select the Input and Output Files

  1. Add the PDF Converter activity to the Canvas and complete the common activity properties.

  2. Click the PDF Converter tab.

  3. Click the Input File Pointer drop-down list and select the FilePointer Data Item that will contain the file you want to convert to PDF.

  4. Click the Output FilePointer drop-down list and select the FilePointer Data Item that you want to contain the PDF file that this activity creates.

  5. Click the Set Name button.

  6. If you want to enter static text for the file name, then click in the large text box and enter the file name.

  7. If you want to insert a Data Item value, then select either the Display Value or Value option, then click the Available Data Items drop-down list and select the Data Item you want to insert.

  8. If you want to insert a Non-Data Item Value, then click the Available Non Data Items drop-down list and select the value you want to insert.

  9. Optionally, select the Append Unique String to Name option to add a unique number to the end of the file name when it is created.

  10. Click OK when you are done creating the file name.

  11. If you want to password protect the output PDF, select the Use PDF Document Security option and set a password for the output PDF.


About the Scripting Activity

The Scripting activity allows you to use custom VBScript or JavaScript coded programs to support a particular activity within a process. Scripts use data values called parameters, which act as either the input or output values for a given script. You (or whoever writes the script) will define any necessary parameters.

With the Scripting activity, it is possible to create and use a program that acts as a complete, new activity that addresses a specific process need in your organization. However, you need extensive knowledge of VBScript or JavaScript coding languages to create a functional script.

Note:

BPM Suite comes with some stock scripts that you can use as reference when creating new scripts.

Working with Existing Scripts

If there are already coded scripts relevant to the process you are designing in the BPM Designer system, then you can use them in the process.

  • Using an Existing Script File with the Scripting Activity

  • Adding a Parameter to an Assigned Script

  • Removing a Parameter from an Assigned Script

  • Importing a Script File

  • Exporting a Script File

  • Deleting a Script File

Working with New Scripts

If you need a new script, you can create, write, edit, and test it.

  • Creating a VB Script File for the Scripting Activity

  • Creating a JavaScript File for the Scripting Activity

  • Writing a Script

  • Testing a Script


Adding a Parameter to an Assigned Script

Some scripts come with one or more parameters that you can fill with values before a script runs in a process, causing the script to execute differently depending upon the value(s) you enter.

If you are familiar with a script's code, you can create additional parameters in order to execute the script differently.

To add a parameter to an assigned script

  1. Add the Scripting activity to the designer canvas and complete the common activity properties.

    Note:
    Completing common activity properties is essential to create an organized and functional process.

  2. Click the Scripting tab.

  3. Locate the script you want to use in the Available Process Scripts field.

  4. Double-click the script to assign it to this activity.
    If the script has parameters they appear in the Script Parameters for the Currently Assigned Script pane.

  5. Click the Add button.
    A Parameter window opens.

  6. Enter a name for the new parameter.

  7. Click OK.
    The Parameter window closes and the new parameter appears in the Script Parameters for the Currently Assigned Script pane.

  8. Click OK.
    The Properties for Activity window closes.

Related Topics

About the Scripting Activity


Creating a JavaScript File for the Scripting Activity

Example:

If you want to select your Convert Address to GeoCode script from your Geography Management folder within your Scripts folder, you might enter the following:

Scripts/Geography_Management/Convert_Address_to_GeoCode in the Script Path.

Creating a Java Script File for the Scripting Activity

If the Java Script file you need does not exist in BPM Suite, you can create a new script file to use with this process and future processes.

To create a new Java Script file

  1. From the Scripting tab, click the Create New Script button [image].
    The Script Properties window opens.

  2. In the Script Name field, enter a descriptive name for the script.

  3. Using the Script Category drop-down list, select the category to which this script will belong.

    Note:
    To add a category, update the Sys_WorkflowCategory by accessing it via List Management.

  4. In the Script Path field, enter the script path.
    View an example of a path    .

  5. From the Script Language field, click the Java Script radio button.

  6. Click OK.
    The Script Properties window closes, a Script Information Updated message appears, and the script is added to the list of available process scripts.

Related topics

About the Scripting Activity


Creating a VB Script File for the Scripting Activity

If the VB Script file you need does not exist in BPM Suite, you can create a new script file to use with this process and future processes.

To create a VB Script file

  1. From the Scripting tab, click the Create New Script button [image].
    The Script Properties window opens.

  2. In the Script Name field, enter a descriptive name for the script.

  3. Using the Script Category drop-down list, select the category to which this script will belong.

    Note:
    To add a category, update the Sys_WorkflowCategory by accessing it via List Management.

  4. In the Script Path field, enter the script path.
    View an example of a path    .

  5. From the Script Language field, click the VB Script radio button.

  6. Click OK.
    The Script Properties window closes, a Script Information Updated message appears, and the script is added to the list of available process scripts.

Related topics

About the Scripting Activity


Deleting a Script File

In the Properties for Activity window of the Scripting activity, you can remove scripts from tasks using the Scripting Task property tab.

To delete a script file

  1. From the Scripting tab, click the Delete the Current Script button [image].
    The Delete Script dialog appears.

    Note:
    Removing a script affects all tasks using that script.

  2. Click Yes.
    The script is permanently removed and a Script Delete confirmation message appears.

  3. Click OK.

Related topics

About the Scripting Activity


Editing Parameters of a Script File

Editing assigned scripts

Editing a script affects all tasks using that script. To edit an assigned script you can do any of the following:

To edit script parameter

To edit script parameters, you can add or delete parameters, or edit parameter values.

To

Do the following

Add a parameter

  1. From the Scripting Task property tab, click Add.
    The Parameter window opens.

  2. Enter the name of the parameter.

  3. Click OK.
    The new parameter appears in the Script Parameters for the Currently Assigned Script array.

  4. Enter the Data Item of the parameter in the Value field.

  5. Click Apply.

Delete a parameter

  1. From the Scripting Task property tab, click the parameter you want to delete.

  2. Click Remove.

  3. Click Apply.

Edit a parameter value

  1. From the Scripting Task property tab, click the parameter value you want to edit.

  2. Enter the new parameter's Data Item in the Value field.

  3. Click Apply.

Related topics

About the Scripting Activity


Editing Properties of a Script File

Example:

If you want to select your Convert Address to GeoCode script from your Geography Management folder within your Scripts folder, you might enter the following:

Scripts/Geography_Management/Convert_Address_to_GeoCode in the Script Path.

Editing assigned scripts

Editing a script affects all tasks using that script. To edit an assigned script you can do any of the following:

To edit script properties

  1. From the Scripting tab, click the Edit Script Properties button.
    The Script Properties window opens.

  2. Edit any of the following script properties:

    • Script Name - in this field you can edit the name of the script.

    • Script Category - from this drop-down list, you can select a script category.

    • Script Path - in this field, you can enter the script path.
      View an example of a path      .

    • Script Language - from these radio buttons, you can select the script language: VB Script or Javascript.

  3. Click OK.
    The Script Properties window closes and a Script Information Updated message appears.

  4. Click Apply to save your edits.

Related topics

About the Scripting Activity


Exporting a Script File

Using the Process Script Management window, you can export a script file. This exported script file can then be imported into a new BPM Suite environment or updated in an external editor an imported back into the same environment.

To export a script file

  1. From the Process Mgmt menu, select Edit Process Script.
    The Process Script Management window opens.

  2. Double-click a script from the Available Process Scripts list.
    The script appears in the Script Editor.

  3. From the Process Script Management toolbar, click the Export Script to File button [image].
    The Save As window opens.

  4. Navigate to the location to which you want to save the script.

  5. In the File Name field, enter the name of the script.
    The file should have a *.wfs extension.

  6. Click the Save button.
    Process script files save with a *.wfs extension, and a Script Export confirmation message appears.

Related topics

About the Scripting Activity


Importing a Script File

Using the Process Script Management window, you can import a script file that was exported from one environment or created in a text editor.

To import a script file

  1. From the Process Mgmt menu, select Edit Process Script.
    The Process Script Management window opens.

  2. Double-click a script from the Available Process Scripts list.
    The script appears in the Script Editor.

  3. From the Process Script Management toolbar, click the Import Script from File button [image].
    The Open window opens.

  4. Navigate to the script you want to import.

    Note:
    Process script files have a *.wfs extension.

  5. Click Open.
    The script opens in the Script Editor.

Related topics

About the Scripting Activity


Reference - Creating a Script

Example:

If you want to select your Convert Address to GeoCode script from your Geography Management folder within your Scripts folder, you might enter the following:

Scripts/Geography_Management/Convert_Address_to_GeoCode in the Script Path.

  1. From the Scripting Activity property tab, click the Create New Script button [image].
    The Script Properties window opens.

  2. In the Script Name field, enter a descriptive name for the script.

  3. From the Script Category drop-down list, select the category to which this script will belong.

    Note:
    To add a category, update the Sys_WorkflowCategory by accessing it via List Management.

  4. In the Script Path field, enter the script path.
    View an example of a path    .

  5. Select the script language (either VB Script or Javascript) by using the radio buttons.

  6. Click OK.
    The Script Properties window closes, a Script Information Updated message appears, and the script is added to the list of available process scripts.


Removing a Parameter from an Assigned Script

Adding a Parameter to an Existing Script

Some scripts come with one or more parameters that you can fill with values before a script runs in a process, causing the script to execute differently depending upon the value(s) you enter.

If you are familiar with a script's code, you can create additional parameters in order to execute the script differently.

To add a parameter to an existing script

  1. Add the Scripting activity to the designer canvas and complete the common activity properties.

    Note:
    Completing common activity properties is essential to create an organized and functional process.

  2. Click the Scripting tab.

  3. Locate the script you want to use in the Available Process Scripts field.

  4. Double-click the script to assign it to this activity.
    If the script has parameters they appear in the Script Parameters for the Currently Assigned Script pane.

  5. Click the Add button.
    A Parameter window opens.

  6. Enter a name for the new parameter.

  7. Click OK.
    The Parameter window closes and the new parameter appears in the Script Parameters for the Currently Assigned Script pane.

  8. Click OK.
    The Properties for Activity window closes.

Related Topics

About the Scripting Activity


Testing a Script

You can use the Edit Process Scripts window to test scripts.

To test a script

  1. Click the Process Management menu and select Edit Process Scripts.
    The Process Script Management window appears.

  2. Navigate the Available Process Scripts tree and double click the script you want to test.
    The script appears in the Script Editor.

  3. Click the Test Script tab.
    The process variables and values appear under Available Process Variable and Values for Testing.

  4. Click the Run Script button.
    The script results appear.

    Note:
    From the Test Script tab, you can also do the following:

    • Save the test variables - Click the Save Test Variable button and save as a *.wtd file.

    • Load test variable - Click the Load Test Variable button and load the variables from a *.wtd file.

Related Topics

About the Scripting Activity


Using an Existing Script File with the Scripting Activity

Using an Existing Script in a Process

If your organization has preexisting scripts, then you can use them in a Scripting activity.

To use an existing script in a process

  1. Add the Scripting activity to the designer canvas and complete the common activity properties.

    Note:
    Completing common activity properties is essential to create an organized and functional process.

  2. Click the Scripting tab.

  3. Locate the script you want to use in the Available Process Scripts field.

  4. Double-click the script to assign it to this activity.
    If the script has parameters, they will populate the Script Parameters for the Currently Assigned Script pane.

  5. If necessary, complete the Script Parameters for the Currently Assigned Script field.

    Note:
    Parameters may be Data Items or constant values.

  6. In the Script Parameters for the Currently Assigned script table, enter the Data Items used by this script in the Value column.

  7. Optional: Click the Add button to add a parameter to the current script.

  8. Click OK to close the Properties window.

Related topics

About the Scripting Activity


Writing a Script

After you create a script, you can add code to the script using VBScript or JavaScript, depending on the type of script created.

Note:
This topic requires you to have an understanding and knowledge of VBScript or JavaScript. Without this knowledge, you will not be able to successfully write a script.

To write a script

  1. Add the Scripting Activity to the designer canvas and complete the common activity properties.

    Note:
    Completing common activity properties is essential to create an organized and functional process.

  2. Click the Scripting tab.

  3. Create a Script.

  4. Locate the script you want to use in the Available Process Scripts field.

  5. Double-click the script to assign it to this activity.
    The script's name appears in the Currently Assigned Script field.
    If the script has parameters, they will populate the Script Parameters for the Currently Assigned Script pane.

  6. Click the Edit the Currently Assigned Script button [image].
    The Scripting Console window opens.

    Note:
    The script will have a large amount of sample script already in it. This sample script is deactivated, denoted by its green color. To activate (and use) the sample script, delete the apostrophe at the beginning of each line. The sample script will loose its green color, indicated that it is activated.

  7. In the Edit Script pane, write your script.

  8. When finished, click the Save button.

  9. Click the X in the upper right hand corner of the window.
    The Scripting Console closes.

Related Topics

About the Scripting Activity


About the Set Data Item Activity

About the Set Data Items Activity

The Set Data Items activity allows you to set the value (or change the value) of Data Items to either a constant value or an equated value. You can use the Set Data Item activity to manipulate Data Items in the following two ways:

  • Setting Data Items to a Constant Value

  • Setting Data Items to an Equated Value

Required Auxiliary Topics

Before you configure a Set Data Items activity, create Data Items for which you want to populate or set the values.

  • Create Data Items


Setting a Data Item to a Constant Value

Set a Data Item to constant value when you want to define an explicit value for that Data Item.

To set a Data Item to a constant value

  1. Add the Set Data Item Value activity to the designer canvas and complete the common activity properties.

  2. Click the Set Data Items tab.

  3. Using the drop-down list in the first open field in the Data Items column of the Set Data Items as follows table, select the Data Item that you want to set.
    The Data Item's data type appears in the field under the Type column.

  4. Under the Value column, click the empty field that corresponds to the row of the data item you want to set.
    A cursor appears in the empty field.

  5. Enter the value that you want to set the Data Item to in a set of quotations ( " " ).

    Important
    Make sure to include quotations around the value ( " " ). If you do not include quotations, the BPM Engine may not be able to read it.

  6. Click OK.
    The Properties for Activity window closes.

When the activity executes, it will set all the Data Items you selected according to the values you entered.

Related Topics

About the Set Data Item Activity


Setting a Data Item to an Equated Value

When you configure a Set Data Item activity to set data items to an equated value, the activity allows you to create an expression that can incorporate multiple Data Items and functions used in Microsoft Excel.

Set Data Items to an equated value when the Data Items' values need to be calculated by combining other Data Item values.

Example:
To populate a Data Item called New_Account_Balance with a computed value, you can use the Set Data Item activity to add the value of an Account_Balance Data Item to the value of an Interest Data Item to get the equated value of New_Account_Balance. The equation would look like the following:

%AccountBalance.Value% + %Interest.Value%

Example:

You can also use common Microsoft Excel functions to populate the value of a Data Item. If you want to populate a Data Item with the current date, you can use the Date function, which is simply the following:

Date

To set a Data Item to an equated value

  1. Add the Set Data Item Value activity to the designer canvas and complete the common activity properties.

  2. Click the Set Data Items tab.

  3. Using the drop-down list in the first open field in the Data Items column of the Set Data Items as follows table, select the Data Item that you want to set.
    The Data Item's data type appears in the field under the Type column.

  4. Under the Value column, click the empty field that corresponds to the row of the data item you want to set.
    A cursor and an ellipses button [image] appear in the empty field.

  5. Click the ellipses button.
    A Set Value - [Data Item Name] window opens.

  6. Write and test the logical expression equation that you want the activity to use to set the data item.

  7. Click OK.
    The Set Value - [Data Item Name] window closes.

  8. Click OK.
    The Properties for Activity window closes.

When the activity executes, it will set the values for the Data Items you selected using the results of the equations that you created.

Related Topics

About the Set Data Item Activity


About the Sub Process Activity

Use a Sub Process activity to start a child process within a main (i.e. parent) process. You can map Data Items between the parent and child process(es), allowing the processes to share information. Remember, a sub process is a complete process, meaning that a sub process can have sub processes within it as well.

Note:
Mapping Data Items is a one-to-one mapping. You cannot map a single Data Item in one process to multiple Data Items in another process.

Creating Sub Process Types

You can create two types of sub-processes:

  1. Synchronous - the child process must complete before the parent process can continue

  2. Asynchronous - the child process allows the parent process to continue before it completes

You can view instructions for creating the two sub process types by clicking the following links.

  • Creating a Synchronous Sub Process

  • Creating an Asynchronous Sub Process

Mapping Main Process Data Items to a Sub Process

  • Mapping Individual Data Items to a Sub Process

  • Mapping Selected Data Item Groups to a Sub Process

  • Auto-Mapping Similar Data Items Between Processes

Creating Sub Process Data Items Mappings that Rewrite Main Process Data Items

  • Mapping Writable Sub Process Data Items

  • Allowing Mapped Sub Process Data Items to be Writable


Allowing Mapped Sub Process Data Items to be Writable

Allowing Mapped sub process Data Items to be writable causes the sub process to rewrite Data Items and then enter the new values back into to the main process. Below, you will learn how to make Data Items that have already been mapped writable.

To allow mapped sub process Data Items to be writable

  1. Create either a synchronous or asynchronous sub process.

  2. Click the Edit Data Mappings button [image].
    The Map Data Items between the Main Process and Sub Process window opens.

  3. If required, map the Data Items using one of the following methods:

    4. Map Individual Data Items to a Sub Process

    5. Map Selected Data Item Groups to a Sub Process

    6. Auto-Map Similar Data Items

Note:
After you map the Data Items, they appear in the Data mapping options between processes pane.

  4. In the Data Mapping Options between Processes table, click the sub process Data Item that you want to rewrite the main process Data Item when the sub process executes.
    The Data Item's row is highlighted.

  5. Click the Write Back to Main Process check box, located at the bottom of the window.

  6. Repeat steps 4-5 to make more sub process Data Items writable.

  7. Click Close.
    The Map Data Items between main process and sub process window closes.

  8. Click OK.
    The Properties for Activity window closes.

The sub process Data Item will rewrite the value of the main process Data Item once the sub process executes.

Related Topics

About the Sub Process Activity


Auto-Mapping Data Items Between Processes

If the Data Items in the parent process are named the same as the Data Items in a child process, you can use the Map All Data Items feature to map all matching Data Items between the two processes.

To auto-map similar Data Items between processes

  1. Create either a synchronous or asynchronous sub process.

  2. Click the Edit Data Mappings button [image].
    The Map Data Items between the Main Process and Sub Process window opens.

  3. Click the Map All button [image].
    The mapped Data Items appear in the Data mapping options between processes pane.

  4. Click Close.
    The Map Data Items between main process and sub process window closes.

  5. Click OK.
    The Properties for Activity window closes.

All unreserved main process Data Items with the same name as sub process Data Items are auto-mapped to the respective sub process Data Items.

Related Topics

About the Sub Process Activity


Creating a Synchronous Sub Process

Use a synchronous sub process when you want the main process to wait for the sub process to complete before it continues. This sub process type is ideal for when the main process immediately requires information produced by the sub process in order to proceed.

To create a synchronous sub process

  1. Add the Sub Process activity to the designer canvas and complete the common activity properties.

    Note:
    Completing common activity properties is essential to create an organized and functional process.

  2. Click the Subprocess Properties tab.

  3. Click the ellipsis button next to the Select a process as a subprocess field.
    The Select Subprocess window opens.

  4. Double-click the process you want to link as a sub process.
    The Select Subprocess window closes, and the process appears in the Select a process as a subprocess field.

  5. Using the Synchronization options drop-down list, select (Synchronous) Synchronize with parent process.

  6. Map Data Items from the parent process to the child process using any of the following methods.

    • Mapping Individual Data Items to a Sub Process

    • Mapping Selected Data Item Groups to a Sub Process

    • Auto-Mapping Similar Data Items Between Processes

Note:
If you want the sub process to write data back to the main process, map Writable Data Items.

  7. Click OK.
    The Properties for Activity window closes.

When the activity executes, the sub process must complete before the main process can continue.

Related Topics

About the Sub Process Activity


Creating an Asynchronous Sub Process

Use an asynchronous sub process when you want to allow the main process to continue before the sub process completes.

To create an asynchronous sub process

  1. Add the Sub Process activity to the designer canvas and complete the common activity properties.

    Note:
    Completing common activity properties is essential to create an organized and functional process.

  2. Click the Subprocess Properties tab.

  3. Click the ellipsis button next to the Select a process as a subprocess field.
    The Select Subprocess window opens.

  4. Double-click the process you want to link as a sub process.
    The Select Subprocess window closes, and the process appears in the Select a process as a subprocess field.

  5. Using the Synchronization options drop-down list, select (Asynchronous) Do not synchronize with parent process.
    A Sub Process Synchronization window appears, notifying you of the Asynchronous option consequences.

  6. Click Yes.

  7. Map Data Items from the parent process to the child process using any of the following methods.

    • Mapping Individual Data Items to a Sub Process

    • Mapping Selected Data Item Groups to a Sub Process

    • Auto-Mapping Similar Data Items Between Processes

Note:
If you want the sub process to write data back to the main process, map Writable Data Items.

  8. Click OK.
    The Properties for Activity window closes.

When the activity executes, the sub process will allow the main process to continue before it completes.

Related Topics

About the Sub Process Activity


Mapping Individual Data Items to a Sub Process

Use this sub process Data Item mapping method if you want to map individual Data Items, one at a time.

Note:

You can only map global Data Items if BPM Suite does not use them to manage the process. Data Items like FlowDefID are "reserved" because every process (both main and sub) uses them to identify itself within BPM Suite.

To map individual Data Items to a sub process

  1. Create either a synchronous or asynchronous sub process.

  2. Click the Edit Data Mappings button [image].
    The Map Data Items between the Main Process and Sub Process window opens.

  3. In the Main Process pane, select a Data Item that you want to map to a sub process Data Item.

  4. In the Subprocess pane, select a Data Item to which you want to map the main process Data Item.

  5. Click the Map button [image].
    Both Data Items appear in the Data mapping options between processes pane, under their respective columns.

  6. Repeat steps 3-5 to map additional individual Data Items.

  7. When finished mapping Data Items, click Close.
    The Map Data Items between the Main Process and Sub Process window closes.

  8. Click OK.
    The Properties for Activity Window closes.

The sub process Data Item(s) you selected receives the data stored by the main process data item(s) you selected.

Related Topics

About the Sub Process Activity


Mapping Selected Data Item Groups to a Sub Process

Use this sub process Data Item mapping method if you want to map several Data Items with the same name between a main and sub process.

Note:
You cannot map reserved Data Items because only BPM Suite can change their value.

To map selected Data Item groups to a sub process

  1. Create either a synchronous or asynchronous sub process.

  2. Click the Edit Data Mappings button [image].
    The Map Data Items between the Main Process and Sub Process window opens.

  3. Press and hold down the Ctrl key on your keyboard.

    Note:
    Holding down the Ctrl key allows you to select multiple Data Items at once.

  4. While holding the Ctrl key, select the Data Items from the Main Process pane that you want to map to sub process data items.
    The Map Selected button is highlighted once you select more than one Data Item.

  5. When done selecting Data Items, release the Ctrl key and click the Map Selected button [image].
    The mapped Data Items appear in the Data mapping options between processes pane.

  6. Click Close.
    The Map Data Items between main process and sub process window closes.

  7. Click OK.
    The Properties for Activity window closes.

The main process Data Items you selected are mapped to the respective sub process Data Items with the same name.

Related Topics

About the Sub Process Activity


Mapping Writable Sub Process Data Items

Mapping Writable sub process Data Items allows the sub process to rewrite Data Items and then enter the new values back into to the main process. Below, you will learn how to make sub process Data Items writable as you map them.

To map writable sub process Data Items

  1. Create either a synchronous or asynchronous sub process.

  2. Click the Edit Data Mappings button [image].
    The Map Data Items between the Main Process and Sub Process window opens.

  3. Click the Writable checkbox before you map the Data Items.

    Note:
    If you want to map Non-Writable Data Items, un-check the check box.

  4. Map the Data Items using a one of the following methods:

    • Map Individual Data Items to a Sub Process

    • Map Selected Data Item Groups to a Sub Process

    • Auto-Map Similar Data Items

  5. Click Close.
    The Map Data Items between main process and sub process window closes.

  6. Click OK.
    The Properties for Activity window closes.

The sub process Data Items will rewrite the value of the main process Data Items once the sub process executes.

Related Topics

About the Sub Process Activity


Reference - Auto-Mapping Similar Data Items

  1. Click the Edit Data Mappings button [image].
    The Map Data Items between the Main Process and Sub Process window opens.

  2. Click the Map All button [image].
    All unreserved main process Data Items with the same Name as sub process Data Items are auto-mapped to the respective sub process Data Items.
    The mapped Data Items appear in the Data mapping options between processes pane.

  3. Click Close.
    The Map Data Items between main process and sub process window closes.


Reference - Mapping Individual Data Items to a Sub Process

  1. Click the Edit Data Mappings button [image].
    The Map Data Items between the Main Process and Sub Process window opens.

  2. In the Main Process pane, select a Data Item that you want to map to a sub process Data Item.

  3. In the Subprocess pane, select a Data Item to which you want to map the main process Data Item.

  4. Click the Map button [image].
    The sub process Data Item you selected receives the data stored by the main process data item you selected.
    Both Data Items appear in the Data mapping options between processes pane, under their respective columns.

  5. Repeat steps 3-5 to map additional individual Data Items.

  6. When finished mapping Data Items, click Close.
    The Map Data Items between the Main Process and Sub Process window closes.


Reference - Mapping Selected Data Item Groups to a Sub Process

  1. Click the Edit Data Mappings button [image].
    The Map Data Items between the Main Process and Sub Process window opens.

  2. Press and hold down the Ctrl key on your keyboard.

    Note:
    Holding down the Ctrl key allows you to select multiple Data Items at once.

  3. While holding the Ctrl key, select the Data Items from the Main Process pane that you want to map to sub process data items.
    The Map Selected button is highlighted once you select more than one Data Item.

  4. When done selecting Data Items, release the Ctrl key and click the Map Selected button [image].
    The main process Data Items you selected are mapped to the respective sub process Data Items with the same Name.
    The mapped Data Items appear in the Data mapping options between processes pane.

  5. Click Close.
    The Map Data Items between main process and sub process window closes.


CAP - Automated Activities

  1. Click the Automated Activities category in the Toolbox.

  2. Double-click the activity you want to add, or drag it to the Canvas.
    The activity is added to the process.

  3. Open the Properties for the activity (double-click the activity or right-click and select Activity Properties).
    The Properties window appears.

  4. Complete the common activity properties.


About the SQL Executer

About the SQL Executer Activity

The SQL Executer activity allows you to write SQL statements that update the information stored in database tables. You can call stored procedures and perform more complex queries, like table joins, using the SQL Executor.

Note:

This activity requires the ability to write SQL statements. You may require the assistance of SQL Enterprise Manager or a Database Administrator (DBA) to adequately configure this task.

  • Writing a SQL Statement

  • Storing the Returned Database Error Message in a Data Item

  • Testing a SQL Statement

Required Auxiliary Topics

If you will be using Data Items to write a SQL statement, or if you will be storing any database error messages in a Data Item, then you need to create those Data Items before you configure the activity.

  • Creating Data Items


Storing an Error Message Returned by a SQL Query in a Data Item

If a SQL statement fails, the database it was querying will return an error message. You can configure the SQL Executer activity to capture and store this error message in a Data Item so that a user can view the error message, if needed, at a later point in the process.

To store an error message returned by a SQL query in a Data Item

  1. Add the SQL Executer activity to the designer canvas and complete the common activity properties.

  2. Click the SQL Executor tab.

  3. Write a SQL statement.

  4. Using the Which Data Item should receive database error message? drop-down list, select the Data Item that you want to store the database error message.
    The Data Item you selected is assigned to store the database error message.

  5. Click OK.
    The Properties for Activity window closes.

When the activity executes, if the SQL statement encounters a database error, it will store the error message in the Data Item you selected.

Related Topics

About the SQL Executer


Testing a SQL Statement

Before you run a SQL statement in an activity, you can test it to make sure that it will run correctly.

To test a SQL Statement

  1. Add the SQL Executer activity to the designer canvas and complete the common activity properties.

  2. Click the SQL Executor tab.

  3. Write a SQL statement.

  4. Click the Test SQL Statement button.
    The SQL Execute - Test SQL Statement window opens.

  5. In the Parameters pane, enter values for each parameter in your SQL statement.

  6. Verify that the Use Transaction and Rollback checkbox is checked.

    Important:
    If the Use Transaction and Rollback checkbox is not checked, then the SQL statement test will permanently change the values in the table you are writing to.

  7. Click OK.
    A SQL Executer - Test SQL Results window opens.

  8. Review the SQL test results.

  9. Click OK.
    The SQL Executer - Test SQL Results window closes.

Related Topics

About the SQL Executer


Writing a SQL statement

By writing a SQL statement, you have full control over the query to be executed.

Note:

You may require the assistance of SQL Enterprise Manager or a Database Administrator (DBA) to adequately configure this task.

To execute a custom SQL statement

  1. Add the SQL Executer activity to the designer canvas and complete the common activity properties.

  2. Click the SQL Executor tab.

  3. Click the Database Connection Profile drop-down list and select the database connection you want to use.

    Note:
    To define a new database connection string, refer to Database Connection Management.

  4. Enter your SQL statement in the SQL Statement field.

    Note:
    To include the Display Value of a Data Item in your SQL statement, place your cursor where you want the Data Item display value to appear, then select the Data Item from the Available Data Items list, and finally click the Insert Display Value button. Use the Insert Value button to insert the value of the Data Item.

  5. Click OK to close the Properties window.

When the activity executes, it will execute the SQL statement you entered.

Related Topics

About the SQL Executer


About the SQL Query Activity

The SQL Query activity allows you to write SQL statements that read information from a database and then copy that information into Data Items or save it to an XML file.

Note:

This activity requires the ability to write SQL statements. You may require the assistance of SQL Enterprise Manager or a Database Administrator (DBA) to adequately configure this task.

  • Connecting to a Database and Writing the SQL Query

  • Saving Error Messages to a Data Item

  • Storing the Retrieved Information in Data Items

  • Storing the Retrieved Information as XML

  • Testing the SQL Query

Required Auxiliary Topics

You will need to create a Database Connection profile in order to access the database that contains the information you want to retrieve.

  • Adding Database Connections

You may want to use Data Items in the SQL statement you write, and you may want to store any database error messages in a Data Item. If so, then you need to create those Data Items before you configure the activity.

  • Creating Data Items


Connecting to Database and Writing SQL Query

Connecting to a Database and Writing the SQL Query

Before you can write a SQL Query, you need to select the Database Connection Profile that describes how to connect to the database. If you have not already defined the Database Connection Profile, please see Adding Database Connections. After you select the Database Connection Profile, you can enter any SQL query or stored procedure.

Note:

You may require the assistance of SQL Enterprise Manager or a Database Administrator (DBA) to adequately configure this task.

To execute a custom SQL statement

  1. Add the SQL Query activity to the Canvas and complete the common activity properties.

  2. Click the SQL Query tab.

  3. Click the Database Connection Profile drop-down list and select the database connection you want to use.

    Note:
    To define a new database connection string, please see Adding Database Connections.

  4. Enter your SQL query in the SQL Query field.

    Note:
    To include the Display Value of a Data Item in your SQL statement, place your cursor where you want the Data Item display value to appear, then select the Data Item from the Available Data Items list, and finally click the Insert Display Value button. Use the Insert Value button to insert the value of the Data Item.

  5. Click Validate Query and Return Schema to ensure that the database connection and SQL query are valid.

    Note:     If your query does not validate, you cannot go on to map information in the database to Data Items. Make sure that the connection profile you created is functioning correctly and that your SQL query is valid, then try to validate the query again.

  6. Optionally, you can select a Data Item to contain any error messages that occur when the SQL query runs.

  7. After the SQL query validates, you can:

    • Store the Retrieved Information in Data Items

    • Store the Retrieved Information as XML


Saving Error Messages to a Data Item

If a SQL query fails, the database will return an error message. You can configure the SQL Query activity to capture and store this error message in a Data Item so that a user can view the error message, if needed, at a later point in the process.

To store an error message to a Data Item

  1. Add the SQL Query activity to the Canvas and complete the common activity properties.

  2. Click the SQL Query tab.

  3. Select the Connection Profile and write a SQL query.

  4. Click the Data Item drop-down list, locate inside the Error Message group box, and select the Data Item that you want to store the database error message.

  5. Click OK.
    The Properties window closes.

If the SQL statement creates a database error when the activity runs, the activity will store the error message in the Data Item you selected.

Related Topics

About the SQL Query Activity


Storing the Retrieved Information as XML

After you select the Database Connection Profile, write the SQL query, and validate the query, you can select a Data Item that will contain the information that the SQL query returns as XML.

Note:

You may require the assistance of SQL Enterprise Manager or a Database Administrator (DBA) to adequately configure this task.

To save the SQL query results as an XML file

  1. If you have not already done so, you must:

    • Add the SQL Query activity to the Canvas and complete the common activity properties

    • Set up the database connection and write the SQL query

  2. Click the Data Item Mapping sub-tab.

  3. Select the Save results as XML option at the bottom of the window.

  4. Click the Data Item drop-down list and select the Data Item that you want to contain the XML returned by the SQL query.

    Note:
    If you select a regular Data Item, the XML will be stored in the Data Item. However, if you select a FilePointer Data Item, the XML will be written to the linked file. Also, the Edit File Name button will become enabled and you can define the name of the file that will contain the XML.

  5. Click OK.
    The     Properties window closes.


Storing the Retrieved Information in Data Items

After you select the Database Connection Profile, write the SQL query, and validate the query, you can select Data Items that will contain columns of results returned by the SQL query.

Note:

You may require the assistance of SQL Enterprise Manager or a Database Administrator (DBA) to adequately configure this task.

To save the SQL query results in Data Items

  1. If you have not already done so, you must:

    • Add the SQL Query activity to the Canvas and complete the common activity properties

    • Set up the database connection and write the SQL query

  2. Click the Data Item Mapping sub-tab.

  3. Select the Populate selected Data Items option at the top of the window.

  4. If your SQL query returned multiple record sets, you can click the Available Record Sets drop-down list and select the record set that you want.

    Note:
    The record sets are numbered (starting with zero) in the order you entered each query on the Connection Profile and SQL Query sub-tab.

  5. Click the empty cell at the bottom of the Data Item column and select the Data Item that you want to populate.

  6. Click the empty cell at the bottom of the Table Column column and select the table column you want to store.

  7. Optionally, select Clear Existing Values? to remove any other values that might already be in the Data Item you selected.

  8. Optionally, click the Key drop-down list and select the table column that contains the unique values you want to use to keep the values in each column in the correct order.

  9. Optionally, click the Parent Key drop-down list and select the table column that contains the unique values you want to use to keep the values in each column in the correct order.

  10. Click OK.
    The Properties window closes.


Testing the SQL Query

Before you run a SQL query in an activity, you can test it to make sure that it returns the results you expect.

To test a SQL Query

  1. If you have not already done so, you must:

    • Add the SQL Query activity to the Canvas and complete the common activity properties

    • Set up the database connection and write the SQL query

  2. Click the Test SQL Query sub-tab.

  3. Click the Test SQL Query button.
    The Query results grid displays the result of your SQL query.

  4. Click OK.
    The Properties window closes.

Related Topics

About the SQL Query Activity


About the Table Reader Activity

You can use the Table Reader activity to read data from an existing table on many types of databases. Additionally, you can store the data you read from a database table in Data Items and use them in activities in your process.

Note:

You may require the assistance of SQL Enterprise Manager or a Database Administrator (DBA) to adequately configure this task.

  • Reading Entire Columns from a Database Table

  • Reading Selected Cells within a Database Table

  • Previewing SQL Query Results

  • Setting an Instance and Parent Key for Multi-Value Table Reader Outputs

    Note:
    If the data returned by the Table Reader will be used in a Scripting activity, you can define the instance key and parent key values, which will help you access specific instances of a Data Item in the Scripting activity.

Required Auxiliary Topics

In order to store the outputs for a Table Reader activity, you need to create Data Items in which to sort the data outputs.

  • Creating Data Items


Previewing SQL Query Results

Before you execute a process with a Table Reader activity, you can preview the data that will be returned by the query to ensure that it will return expected values.

To preview the results of a database query

  1. Configure a Table Reader activity.

  2. Click the View SQL Query button.
    The Table Reader - View SQL Query window opens.

  3. Click the Execute Query button.
    The query results will appear in the Query Results pane.

    If necessary, you will be prompted to enter test values in the Query Values window that opens before the query is executed.

  4. Review the query results.

  5. Click the Close button.
    The Table Reader - View SQL Query window closes.

If the query returned the results you expected, then you can be sure that the activity will return the same results when the activity executes.

Related Topics

About the Table Reader Activity


Reading Entire Columns from a Database Table

Using the Table Reader activity, you can read entire columns of data from a database table. After you read them, you can then store all the values in those columns in multiple instance Data Items.

Note:

As a system administrator, you may require the assistance of SQL Enterprise Manager or a Database Administrator (DBA) to adequately configure this task.

To read entire columns from a database table

  1. Add the Table Reader activity to the designer canvas and complete the common activity properties.

  2. Click the Table Reader tab.

  3. Using the Database Connection Profile drop-down list, select the database connection you want to use.

    Note:
    To define a new database connection string, refer to Database Connection Management.

  4. Using the Which Database Table Should be Queried drop-down list, select the table you want to query.

  5. Click the Output to Data Items tab.

  6. Using the drop-down list in the first row under the Data Item column, select a Data Item that will store the values you will retrieve from the table column.

  7. Using the drop-down list in the first row under the Table Column column, select the table column you want to read.
    When executed, the activity will store all of the table column values in the Data Item that you selected.

  8. In a new row for each column you want to read, repeat steps 6-7 to store additional columns of values in Data Items.

    Note:
    Click the     Clear Existing Values check box to remove the checkmark if you do not want to over write the value stored in the selected Data Item. By default this check box is checked, assuming you want to store the new information in the Data Item.

  9. Click OK.
    The Properties for Activity window closes.

Related Activities

About the Table Reader Activity


Reading Selected Cells within a Database Table

In the Data Item column, select the Data Item with the Display Value on which you want to base your query.

In the Data Item column, select the Data Item with the Instance Key on which you want to base your query.

In the Data Item column, select the Data Item with the Value on which you want to base your query.

In the Data Item column, enter the constant value on which you want to base your query.

Reading Selected Information within a Database Table

Using the Table Reader activity, you can read selected cells of data from a database table and store the cells' values in Data Items.

You can read selected cells by identifying a piece of information in a row and then selecting a column. Then, you read the intersection point of the row (of the information you selected) and the column, allowing you to read a selected cell within a database table.

Note:

You may require the assistance of SQL Enterprise Manager or a Database Administrator (DBA) to adequately configure this task.

To read selected information within a database table

  1. Add the Table Reader activity to the designer canvas and complete the common activity properties.

  2. Click the Table Reader tab.

  3. Using the Database Connection Profile drop-down list, select the database connection you want to use.

    Note:
    To define a new database connection string, refer to Database Connection Management.

  4. Using the Which Database Table Should be Queried drop-down list, select the table you want to query.

  5. On the Filter by Column Values tab, using the drop-down list in the first row under Table Column, select the table column that contains the value in the same row as the cell from which you want to read.

  6. In the same row, using the drop-down list under the Source column, select the type of data you want to retrieve.

  7. In the same row, only under the Data Item column, use the drop-down list to select the Data Item that stores the information on which you want to base your cell query. Pick a Data Item that corresponds to the Data Item type you selected in step 6. Refer to the links below for further guidance.

    • .DisplayValue

    • .InstanceKey

    • .Value

    • Constant

  8. Repeat steps 5-7 to filter your query using additional values.

    Note:
    If you are reading from multiple cells, you can choose to read only the cells that meet all of the value conditions by clicking the Match ALL defined conditions option. Or you can choose to read all cells that meet any of the conditions by clicking the Match ANY defined condition option.

  9. Click the Output to Data Items tab.

  10. Using the drop-down list in the first row under the Data Item column, select a Data Item that will store the values you will retrieve from the table column.

  11. Using the drop-down list in the first row under the Table Column column, select the table column you want to read.

  12. In a new row for each cell you want to read, repeat steps 10-11 to store additional cell values in Data Items.

    Note:
    Click the Clear Existing Values check box to remove the check mark if you do not want to append the new values to the selected Data Item. By default this check box is checked, assuming you want to store the new information in the Data Item.

  13. Click OK.
    The Properties for Activity window closes.

When executed, the activity will first reference the row(s) of the value(s) you selected in step 7. Then, it will read the cell value of the cell that is at the intersection point of the column(s) you select in step 11 and the row of the value(s) that you selected in step 7.

Related Topics

About the Table Reader Activity


You retrieve the First Name and Last Name of every one of your customers from a database and store the values in Firstname and Lastname Data Items, respectively. To associate each First Name instance with each corresponding Last Name instance, you set the Customer ID as the key. As a result, you can reference the related name information from the different Data Items because each Firstname and Lastname Data Item instance shares the same Customer ID Key.

You retrieve the Task Name and Task ID of every task that has executed in the past week and store the values in Taskname and TaskID Data Items, respectively. You also set the Task ID as the Key, group each value instance according to each value in the Task ID column. However, you also set the User ID column (containing the user IDs of the users that completed each task) as the parent key. As a result, you can reference all the task information according to what user completed each task on account of the User ID parent key.

Setting an Instance and Parent Key for Multi-Value Table Reader Outputs

If you use a Table Reader activity to populate Data Items with multiple values, you can set a database column as a key for the multiple instances in each Data Item, thus linking their values. Also, you can set a database column as a parent key, allowing the value instances with previous instance keys to associate with all other value instances under the parent key.

By default, the keys are stored as GUIDs, which are not easy to access via Scripting activities. Assigning a value from the database to the keys makes them easier to access.

Important:

The key and parent key of Data Items is set automatically by BPM Suite. The only benefit of setting the keys and parent keys yourself is that you can easily reference them via a Scripting activity.

By setting a database column as a key, you associate each Data Item instance with a corresponding value in the same row of the database column. As a result, instance values in different Data Items are linked to each other on account of their association with a common key value, allowing you to reference instances from separate Data Items that share that key.

Example for Key

Example for Parent Key

To set a key for table reader outputs

  1. Configure a Table Reader activity to read from either entire columns in a database table or selected cells in a database table.

  2. Click the Output to Data Items tab.

  3. Using the Key drop-down list, select a table column you want to act as a key.

  4. Using the Parent Key drop-down list, select a table column you want to act as the parent key.

  5. Click OK.
    The Properties for Activity window closes.

In addition to a name, value and a display value, all data items have a key and a parent key value. The key or parent key values returned by the query are stored with the instance of the data item selected under the Output to Data Items tab.

Related Topics

About the Table Reader Activity


About the Table Writer Activity

You can use the Table Writer activity to insert a new row of data, update an existing row of data, or delete a row of data from a database table. If you use the use the activity to insert or update data, you can enter a static value, select a Data Item with the value, or use an expression.

Note:

You may require the assistance of SQL Enterprise Manager or a Database Administrator (DBA) to adequately configure this task.

  • Inserting a New Row of Information into a Database Table

  • Updating Selected Information in a Database Table

  • Deleting Information from a Database Table

Required Auxiliary Topics

To write to a database table, you must first create Data Items that store the values you want to use to filter the table and possibly also the values you want to write to the table.

  • Creating Data Items


Deleting Information from a Database Table

You can use the Table Writer activity to delete selected information from a database table. After you delete information, the row that contained the information remains blank.

The activity provides a grid that you can use to identify which rows the activity will delete. For example, you might limit the Table Writer to only delete rows where the Name column contains "Phil Baharnd". You can use the grid to enter multiple limitations. For example, you might use the second row in the grid to further limit the Table Writer to only delete rows where the Name column contains "Phil Bahard" and the Employee ID column contains "14096".

Note:

You may require the assistance of SQL Enterprise Manager or a Database Administrator (DBA) to adequately configure this task.

To delete information from a database table

  1. Add the Table Writer Activity to the Canvas and complete the common activity properties.

  2. Click the Table Writer tab.
    The Select Database and Table tab is in front.

  3. Click the Database Connection Profile drop-down list and select the database that contains the table to which you want to add a row of information.

    Note:
    The drop-down list shows the options in the Database Connection Manager. To define a new database connection string, refer to Database Connection Management.

  4. Click the ellipses button next to the Table field.
    The Select Table window appears.

  5. Select the table where you want to delete one or more rows of information and click Select.
    The name of the table you selected appears in the Table field.

  6. Click the Delete option in the Method section.
    A Criteria table appears in the same section. You can use this grid to identify the rows that you want to delete.

  7. Click the first cell in the Table Column column and use the drop-down list to select a column in the table. The Table Writer will search this column for a value that you are about to enter. Only rows that contain the value you select will be deleted.

  8. Click the Source cell in the same row and select one of the following options:

    • Constant - Select this option if you want to enter a static string of text to match to a value in the table column.

    • DataItem.Display - Select this option if you want to match the Display Value of a Data Item to a value in the table column.

    • DataItem.Value - Select this option if you want to match the Value of a Data Item to a value in the table column.

    • Expression - Select this option if you want to match the result of a logical expression to a value in the table column.

  9. Click the Value cell in the same row of the grid and perform one of the following actions:

    • If you selected Constant, then enter a string of text and/or numbers.

    • If you selected Display Value or Value, then click the cell and use the drop-down list to select a Data Item.

    • If you selected Expression, then enter an expression.

  10. Repeat steps 7-9 to enter more filters. Only rows in the table that contain every table column value you select will be deleted.

  11. Optionally, click the Result tab to view the SQL statement that the Table Writer will use when it runs.

  12. Click OK.
    The Properties window closes.


Inserting a New Row of Information into a Database Table

You can use the Table Writer activity to write a new row of information into a database table.

Note:

You may require the assistance of SQL Enterprise Manager or a Database Administrator (DBA) to adequately configure this task.

To insert a new row of information into a database table

  1. Add the Table Writer activity to the Canvas and complete the common activity properties.

  2. Click the Table Writer tab.
    The Select Database and Table tab is in front.

  3. Click the Database Connection Profile drop-down list and select the database that contains the table to which you want to add a row of information.

    Note:
    The drop-down list shows the options in the Database Connection Manager. To define a new database connection string, refer to Database Connection Management.

  4. Click the ellipses button next to the Table field.
    The Select Table window appears.

  5. Select the table to which you want to add a row of information and click Select.
    The name of the table you selected appears in the Table field.

  6. Select the Insert option, located in the Method section.

  7. Click the Map Values tab.
    A grid displays a list of every column in the selected database table.

  8. Look through the Table Column list and find a table column where you want to add a new value.

  9. Click the Source drop-down list in the same row of the grid.

  10. Select one of the following options:

    • Constant - Select this option if you want to enter a static string of text to insert in the table column.

    • DataItem.Display - Select this option if you want to insert the Display Value of a Data Item in the table column.

    • DataItem.Value - Select this option if you want to insert the Value of a Data Item in the table column.

    • Expression - Select this option if you want to insert the result of a logical expression in the table column.

  11. Click the Value cell in the same row of the grid and perform one of the following actions:

    • If you selected Constant, then enter a string of text and/or numbers.

    • If you selected Display Value or Value, then click the cell and use the drop-down list to select a Data Item.

    • If you selected Expression, then enter an expression.

  12. Repeat steps 8-11 for every table column where you want to insert a value.

  13. Optionally, click the Result tab to view the SQL statement that the Table Writer will use when it runs.

  14. Click OK.
    The Properties window closes.


Updating Selected Information in a Database Table

You can use the Table Writer activity to update (i.e. overwrite) selected rows in a database table. The activity provides a grid that you can use to identify which rows the activity will update. For example, you might limit the Table Writer to only update rows where the Name column contains "Phil Baharnd". You can use the grid to enter multiple limitations. For example, you might use the second row in the grid to further limit the Table Writer to only update rows where the Name column contains "Phil Bahard" and the Employee ID column contains "14096".

Note:

You may require the assistance of SQL Enterprise Manager or a Database Administrator (DBA) to adequately configure this task.

To update selected information in a database table

  1. Add the Table Writer activity to the designer canvas and complete the common activity properties.

  2. Click the Table Writer tab.
    The Select Database and Table sub-tab is in front.

  3. Click the Database Connection Profile drop-down list and select the database that contains the table where you want to update a row of information.

    Note:
    The drop-down list shows the options in the Database Connection Manager. To define a new database connection string, refer to Database Connection Management.

  4. Click the ellipses button next to the Table field.
    The Select Table window opens.

  5. Select the table to which you want to add a row of information and click Select.
    The name of the table you selected appears in the Table field.

  6. Select the Update option in the Method section.
    A Criteria grid appears in the same section. You can use this grid to identify the rows that you want to update.

  7. Click the first cell in the Table Column column and use the drop-down list to select a column in the table. The Table Writer will search this column for a value that you are about to enter. Only rows that contain the value you select will be updated.

  8. Click the Source cell in the same row and select one of the following options:

    • Constant - Select this option if you want to enter a static string of text to match to a value in the table column.

    • DataItem.Display - Select this option if you want to match the Display Value of a Data Item to a value in the table column.

    • DataItem.Value - Select this option if you want to match the Value of a Data Item to a value in the table column.

    • Expression - Select this option if you want to match the result of a logical expression to a value in the table column.

  9. Click the Value cell in the same row of the grid and perform one of the following actions:

    • If you selected Constant, then enter a string of text and/or numbers.

    • If you selected Display Value or Value, then click the cell and use the drop-down list to select a Data Item.

    • If you selected Expression, then enter an expression.

  10. Repeat steps 7-9 to enter more filters. Only rows in the table that contain every table column value you select will be updated.

  11. Click the Map Values tab.
    A grid displays every column in the table you selected on the Select Database and Table tab. You can use this grid to map values to each table column. These values will be overwrite the existing values in any row available based on the selections you made in steps 7-9.

  12. Look through the Table Column column and locate a column where you want to update the value.
    The     Data Type column tells you what type of data is allowed in that column.

  13. Click the Source cell in the same row and use the drop-down list to select one of the following options:

    • Constant - Select this option if you want to enter a static string of text to insert in the table column.

    • DataItem.Display - Select this option if you want to insert the Display Value of a Data Item in the table column.

    • DataItem.Value - Select this option if you want to insert the Value of a Data Item in the table column.

    • Expression - Select this option if you want to insert the result of a logical expression in the table column.

  14. Click the Value cell in the same row and perform one of the following actions:

    • If you selected Constant, then enter a string of text and/or numbers.

    • If you selected Display Value or Value, then click the cell and use the drop-down list to select a Data Item.

    • If you selected Expression, then enter an expression.

  15. Repeat steps 12-14 as necessary to enter values for additional columns.

  16. Optionally, click the Result tab to view the SQL statement that the Table Writer will use when it runs.

  17. Click OK.
    The Properties window closes.


CAP - Database Activities

  1. Click the Database Activities category in the Process Designer toolbox.

  2. Double-click the activity you want to add, or drag it to the Canvas.
    The activity is added to the process.

  3. Open the Properties for the activity (double-click the activity or right-click and select Activity Properties).
    The Properties window appears.

  4. Complete the common activity properties.


About the Email Activity

You can use the Email activity to send Email to internal or external recipients.

In addition to sending Email, the Email activity allows you to send attached files to recipients as well as use advanced formatting in the message text of the Email.

Finally, you can use Data Items to populate Email fields, allowing you to configure the Email activity even if you do not have the information you want to send when you are designing a process.

Create a Plain Text or HTML Email

  • Sending a Plain Text Email

  • Sending an HTML Email

Including a BPM Web Task Link in an Email

If you want to include a link to a task in BPM Web with your email message, you can create it by compiling some available Data Items.

  • Including a BPM Web Task Link in an Email

Required Auxiliary Topics

Before you can attach a file to an Email using the Email activity, you need to create a FilePointer Data Item that will store the name of the file that you want to attach to the Email.

  • Creating a FilePointer Data Item

Also, if you want to populate the Email with Data Items that BPM Suite will replace with the process-produced data associated with each Data Item, then you need to create Data Items and associate them with the desired information.

  • Creating Data Items


Including a Link to BPM Web in an Email

If you are writing an email that instructs someone to complete a task in BPM Web, you can include a Web link to that task by compiling two of the available Data Items.

To Include a Link to BPM Web in an Email

  1. If you have not done so already, compose an email using one of the following methods:

    • Sending a Plain Text Email

    • Sending an HTML Email

  2. Select the Value option beneath the Available Data Items list.

  3. Locate the WebBaseURL Data Item in the Available Data Items list.

  4. Drag the WebBaseURL Data Item to the Email Message field where you want to insert the link to a task in BPM Web.

    Note
    When the email is sent, that Data Item will be replaced with a link to BPM Web. However, you may need to include more information to help the recipient identify which task needs to be completed.

  5. Click OK.
    The Properties window closes.


Sending a Plain Text Email

Select the CC (carbon copy) recipient through one of the following methods:

  • Click the Cc field and enter the email address of the CC recipient.

  • Right-click a Data Item in the Available Data Items list and select Add to Cc.

Note
You can enter multiple recipients if you separate their email addresses with semicolons.

Select the BCC (blind carbon copy) recipient through one of the following methods:

  • Click the Bcc field and enter the email address of the BCC recipient.

  • Right-click a Data Item in the Available Data Items list and select Add to Bcc.

Note
You can enter multiple recipients if you separate their email addresses with semicolons.

Click the Priority drop down list and select Low, Normal, or Urgent.

Changing the email priority does not affect how or when the email is delivered. It communicates the importance of the email to the recipient.

  1. Click the Attachments field.
    An ellipsis button appears in the field.

  2. Click the ellipsis button.
    A window displays a list of every FilePointer Data Item in the current process.

  3. Select one or more FilePointer Data Items to include them as attachments in the email.

  4. Click OK.

Sending a Plain Text Email

You can use the Email activity to send an email to anyone, regardless of whether they are inside your organization or outside. Emails can use plain text or HTML formatting. You can also insert Data Items so that your emails contain dynamic information derived through the BPM process.

To Send a Plain Text Email

  1. Add the Email activity to the Canvas and complete the common activity properties.

  2. Click the Email tab.

  3. Select the email sender through one of the following methods:

    • Click the Sender field and enter the email address of the sender.

    • Right-click a Data Item in the Available Data Items list and select Add to Sender.

    Note
    You do not need to enter a real email address. The "Sender" is just the email address you want to be visible to the email recipient.

  4. Select the email recipient through one of the following methods:

    • Click the Recipient field and enter the email address of the recipient.

    • Right-click a Data Item in the Available Data Items list and select Add to Recipient.

    Note
    You can enter multiple recipients if you separate their email addresses with semicolons.

  5. Select the subject of the email through one of the following methods:

    • Click the Subject field and enter the subject of the email.

    • Right-click a Data Item in the Available Data Items list and select Add to Message Subject.

  6. Optionally, you can select a CC recipient, BCC recipient, or set the email priority.

  7. Optionally, you can attach a file to the email.

  8. Click the Message Type drop-down list and select Plain Text.

  9. Click the Email Message field to enter your message.

  10. Optionally, you can drag Data Items from the Available Data Items list to the Email Message field to insert Data Items in your email.

    Note
    You can select the Display Value or Value option beneath the Available Data Items list to enter one Data Item value or the other.

  11. Click OK.
    The Properties for Activity window closes.


Sending an HTML Email

Select the CC (carbon copy) recipient through one of the following methods:

  • Click the Cc field and enter the email address of the CC recipient.

  • Right-click a Data Item in the Available Data Items list and select Add to Cc.

Note
You can enter multiple recipients if you separate their email addresses with semicolons.

Select the BCC (blind carbon copy) recipient through one of the following methods:

  • Click the Bcc field and enter the email address of the BCC recipient.

  • Right-click a Data Item in the Available Data Items list and select Add to Bcc.

Note
You can enter multiple recipients if you separate their email addresses with semicolons.

Click the Priority drop down list and select Low, Normal, or Urgent.

Changing the email priority does not affect how or when the email is delivered. It communicates the importance of the email to the recipient.

  1. Click the Attachments field.
    An ellipsis button appears in the field.

  2. Click the ellipsis button.
    A window displays a list of every FilePointer Data Item in the current process.

  3. Select one or more FilePointer Data Items to include them as attachments in the email.

  4. Click OK.

Sending an HTML Email

You can use the Email activity to send an email to anyone, regardless of whether they are inside your organization or outside. Emails can use plain text or HTML formatting. You can also insert Data Items so that your emails contain dynamic information derived through the BPM process.

To Send an HTML Email

  1. Add the Email activity to the Canvas and complete the common activity properties.

  2. Click the Email tab.

  3. Select the email sender through one of the following methods:

    • Click the Sender field and enter the email address of the sender.

    • Right-click a Data Item in the Available Data Items list and select Add to Sender.

    Note
    You do not need to enter a real email address. The "Sender" is just the email address you want to be visible to the email recipient.

  4. Select the email recipient through one of the following methods:

    • Click the Recipient field and enter the email address of the recipient.

    • Right-click a Data Item in the Available Data Items list and select Add to Recipient.

    Note
    You can enter multiple recipients if you separate their email addresses with semicolons.

  5. Select the subject of the email through one of the following methods:

    • Click the Subject field and enter the subject of the email.

    • Right-click a Data Item in the Available Data Items list and select Add to Message Subject.

  6. Optionally, you can select a CC recipient, BCC recipient, or set the email priority.

  7. Optionally, you can attach a file to the email.

  8. Click the Message Type field and use the drop-down list to select HTML.
    HTML formatting controls appear in the     Email Message field.

  9. Click the Email Message field to enter your message.

  10. Optionally, you can drag Data Items from the Available Data Items list to the Email Message field to insert Data Items in your email.

    Note
    You can select the Display Value or Value option beneath the Available Data Items list to enter one Data Item value or the other.

  11. Click OK.
    The Properties for Activity window closes.


About the Excel Calculate Activity

You can use Excel Calculate activity to work with Excel 2007 files that are stored in a SharePoint 2007 repository. Although you can read from and write to Excel 2007 files with the Excel 2007 Reader and the Excel 2007 Writer activities, those activities are not able to recalculate the values in cells that use formulas. However, when an Excel 2007 file is stored in a SharePoint 2007 repository, you can use the Excel Calculate activity to read from, write to, and recalculate values in an Excel 2007 document. You can also save the Excel 2007 file to a FilePointer Data Item.

By default, if you modify an Excel file in a SharePoint repository, it will be saved back to the same location in SharePoint. However, you can also save the Excel file to a FilePointer Data Item.

Follow the links below to view the steps for writing, calculating, and reading values from an Excel 2007 document.

Selecting the Excel 2007 file

  • Selecting an Excel 2007 File on SharePoint

Selecting the SharePoint URL of the Excel web service

  • Selecting the SharePoint URL of the Excel Web Service

Writing values in Data Items to the Excel Document

  • Writing Data Item Values to a Column in an Excel Document

  • Writing Data Item Values to a Row in an Excel Document

  • Writing Data Items to Individual Cells in an Excel Document

  • Copying Data Item Mappings from a Previous Excel Activity (Write)

Calculating Formulas in the Excel Document

  • Calculate the Entire Workbook

  • Calculate only Changes in the Entire Workbook

  • Calculate only Formulas within a Worksheet and Cell Range

Reading values in the Excel Document to Data Items

  • Reading a Row of Values from an Excel Spreadsheet

  • Reading a Column of Values from an Excel Spreadsheet

  • Reading Individual Cells from an Excel Spreadsheet

  • Copying Data Item Mappings from a Previous Excel Activity (Read)

Saving the Excel file to a Data Item

  • Saving the Excel File to a Data Item

Required Auxiliary Topics

Before you begin configuring a Excel Calculate Activity, make sure to complete the following:

  • Create Data Items that will store the Excel information the activity will read and write


Calculate only Changes in the Entire Workbook

You can use this option in the Excel Calculate activity to calculate only the formulas that refer to cells whose values have changed. This calculation will apply to affected formulas throughout the workbook, regardless of which worksheet they are on.

If you want to calculate every formula in the workbook, whether or not the cells it refers to have changed, then you can calculate the entire workbook.
If you want to calculate every formula within a worksheet and cell range, then you can set a worksheet name and cell range.

To Calculate only Formulas that have Changed in the Excel Workbook

  1. Add the Excel Calculate activity to the Canvas and complete the common activity properties.

  2. Click the Excel Calculate tab.

  3. If you have not already done so, select the Excel 2007 file on SharePoint that you want to modify.

  4. If you have not already done so, select the SharePoint URL of the Excel Web Service.

  5. If necessary, configure the activity to write Data Item values to the Excel Document using one of the following methods:

    • Writing Data Item Values to a Column in an Excel Document

    • Writing Data Item Values to a Row in an Excel Document

    • Writing Data Items to Individual Cells in an Excel Document

    • Copying Data Item Mappings from a Previous Excel Activity (Write)

  6. Click the Calculate sub-tab.

  7. Select the Enable calculate option.

  8. Select the Workbook (changes only) option.

  9. If necessary, configure the activity to read values from the workbook using one of the following methods:

    • Reading a Row of Values from an Excel Spreadsheet

    • Reading a Column of Values from an Excel Spreadsheet

    • Reading Individual Cells from an Excel Spreadsheet

    • Copying Data Item Mappings from a Previous Excel Activity

  10. If necessary, output the modified file to a Data Item.

    Note
    If you do not output the Excel file to a Data Item, it will still be saved and available through SharePoint.

  11. Click OK to close the Properties window.


Calculate only Formulas within a Worksheet and Cell Range

  1. Click the Start drop-down list and select the Data Item that will contain the coordinates of the cell where you want to start including formulas to calculate.

    For example, you might select a Data Item whose value is A1.

  2. Click the End drop-down list and select the Data Item that will contain the coordinates of the cell where you want to stop including formulas to calculate.

    For example, you might select a Data Item whose value is D9.

  1. Click the Start box and enter the coordinates of the cell where you want to start including formulas to calculate.

    For example, you might enter the coordinate A1.

  2. Click the End box and enter the coordinates of the cell where you want to stop including formulas to calculate.

    For example, you might enter the coordinate D9.

Calculate only Formulas within a Worksheet and Cell Range

You can use this option in the Excel Calculate activity to calculate every formula within a cell range on a specific worksheet.

If you want to calculate every formula in the workbook, whether or not the cells it refers to have changed, then you can calculate the entire workbook.

If you want to calculate only formulas that refer to cells whose values have changed, then you can calculate only changes in the entire workbook.

To Calculate every Formula in the Excel Workbook

  1. Add the Excel Calculate activity to the Canvas and complete the common activity properties.

  2. Click the Excel Calculate tab.

  3. If you have not already done so, select the Excel 2007 file on SharePoint that you want to modify.

  4. If you have not already done so, select the SharePoint URL of the Excel Web Service.

  5. If necessary, configure the activity to write Data Item values to the Excel Document using one of the following methods:

    • Writing Data Item Values to a Column in an Excel Document

    • Writing Data Item Values to a Row in an Excel Document

    • Writing Data Items to Individual Cells in an Excel Document

    • Copying Data Item Mappings from a Previous Excel Activity (Write)

  6. Click the Calculate sub-tab.

  7. Select the Enable calculate option.

  8. Select the Range option.

  9. Set the Cell range through one of the following actions:

    • Select the Select Data Item option and select Data Items that contain the Start and End cell coordinates.

    • Select the Enter value option and then enter the Start and End cell coordinates.

  10. Set the Worksheet name through one of the following actions:

    • Select the Select Data Item option and click the drop-down list to select the Data Item that will contain the name of the worksheet whose formulas you want to include.

    • Select the Enter value option and click the box to enter the name of the worksheet whose formulas you want to include.

  11. If necessary, configure the activity to read values from the workbook using one of the following methods:

    • Reading a Row of Values from an Excel Spreadsheet

    • Reading a Column of Values from an Excel Spreadsheet

    • Reading Individual Cells from an Excel Spreadsheet

    • Copying Data Item Mappings from a Previous Excel Activity (Read)

  12. If necessary, output the modified file to a Data Item.

    Note
    If you do not output the Excel file to a Data Item, it will still be saved and available through SharePoint.

  13. Click OK to close the Properties window.


Calculate the Entire Workbook

You can use this option in the Excel Calculate activity to calculate every formula in the workbook.

If you want to calculate only formulas that refer to cells whose values have changed, then you can calculate only changes in the entire workbook.
If you want to calculate every formula within a worksheet and cell range, then you can set a worksheet name and cell range.

To Calculate every Formula in the Excel Workbook

  1. Add the Excel Calculate activity to the Canvas and complete the common activity properties.

  2. Click the Excel Calculate tab.

  3. If you have not already done so, select the Excel 2007 file on SharePoint that you want to modify.

  4. If you have not already done so, select the SharePoint URL of the Excel Web Service.

  5. If necessary, configure the activity to write Data Item values to the Excel Document using one of the following methods:

    • Writing Data Item Values to a Column in an Excel Document

    • Writing Data Item Values to a Row in an Excel Document

    • Writing Data Items to Individual Cells in an Excel Document

    • Copying Data Item Mappings from a Previous Excel Activity (Write)

  6. Click the Calculate sub-tab.

  7. Select the Enable calculate option.

  8. Select the Workbook option.

  9. If necessary, configure the activity to read values from the workbook using one of the following methods:

    • Reading a Row of Values from an Excel Spreadsheet

    • Reading a Column of Values from an Excel Spreadsheet

    • Reading Individual Cells from an Excel Spreadsheet

    • Copying Data Item Mappings from a Previous Excel Activity (Read)

  10. If necessary, output the modified file to a Data Item.

    Note
    If you do not output the Excel file to a Data Item, it will still be saved and available through SharePoint.

  11. Click OK to close the Properties window.


Copying Data Item Mappings from a Previous Excel Activity (Read)

Instead of manually mapping each value to a Data Item, you can save time while configuring the Read tab of the Excel Calculate activity by copying the Data Item mappings from a previous Excel activity in the process.

You can copy the Data Item mappings from a previous Excel 2007 Reader, Excel 2007 Writer, or Excel Calculate activity.

To copy Data Item mappings from another Excel activity

  1. Add the Excel Calculate activity to the Canvas and complete the common activity properties.

  2. Click the Excel Calculate tab.

  3. If you have not already done so, select the Excel 2007 file on SharePoint that you want to modify.

  4. If you have not already done so, select the SharePoint URL of the Excel Web Service.

  5. If necessary, configure the activity to write Data Item values to the Excel Document using one of the following methods:

    • Writing Data Item Values to a Column in an Excel Document

    • Writing Data Item Values to a Row in an Excel Document

    • Writing Data Items to Individual Cells in an Excel Document

    • Copying Data Item Mappings from a Previous Excel Activity (Write)

  6. If necessary, configure the activity to calculate the formulas in the workbook using one of the following methods:

    • Calculate the Entire Workbook

    • Calculate only Changes in the Entire Workbook

    • Calculate only Formulas within a Worksheet and Cell Range

  7. Click the Read sub-tab.

  8. Select the Manually map Data Items values option.
    The Edit Data Item Mappings button becomes enabled.

  9. Click the Edit Data Item Mappings button.
    The Map Data Items window appears.

  10. Click the Copy Data Item Mappings button.
    The Select Prior Excel Activity window appears.

  11. Select a previous Excel activity from which you want to copy the Data Item mappings.

  12. Click OK.
    The Data Item mappings from the Excel activity you selected appear in the table in the Map Data Items window.

  13. Click OK.
    The Map Data Items window closes.

  14. If necessary, output the modified file to a Data Item.

    Note
    If you do not output the Excel file to a Data Item, it will still be saved and available through SharePoint.

  15. Click OK to close the Properties window.

Related Topics

About the Excel Calculate Activity | Reading a Column of Values from an Excel Spreadsheet | Reading a Row of Values from an Excel Spreadsheet | Reading Individual Cells from an Excel Spreadsheet


Copying Data Item Mappings from a Previous Excel Activity (Write)

Instead of manually mapping each value to a Data Item, you can save time while configuring the Write tab of the Excel Calculate activity by copying the Data Item mappings from a previous Excel activity in the process.

You can copy the Data Item mappings from a previous Excel 2007 Reader, Excel 2007 Writer, or Excel Calculate activity.

To copy Data Item mappings from another Excel activity

  1. Add the Excel Calculate activity to the Canvas and complete the common activity properties.

  2. Click the Excel Calculate tab.

  3. If you have not already done so, select the Excel 2007 file on SharePoint that you want to modify.

  4. If you have not already done so, select the SharePoint URL of the Excel Web Service.

  5. Click the Write sub-tab.

  6. Select the Enable write option.

  7. Select the Map selected Data Items to worksheet cells option.
    The Edit Data Item Mappings button becomes enabled.

  8. Click the Edit Data Item Mappings button.
    The Map Data Items window appears.

  9. Select Map selected Data Items to worksheet cells.

  10. Click the Edit Data Item Mappings button.
    The Map Data Items window appears.

  11. Click the Copy Data Item Mappings button.
    The Select Prior Excel Activity window appears.

  12. Select a previous Excel activity from which you want to copy the Data Item mappings.

  13. Click OK.
    The Data Item mappings from the Excel activity you selected appear in the table in the Map Data Items window.

  14. Click OK.
    The Map Data Items window closes.

  15. If necessary, configure the activity to calculate the formulas in the workbook using one of the following methods:

    • Calculate the Entire Workbook

    • Calculate only Changes in the Entire Workbook

    • Calculate only Formulas within a Worksheet and Cell Range

  16. If necessary, configure the activity to read values from the workbook using one of the following methods:

    • Reading a Row of Values from an Excel Spreadsheet

    • Reading a Column of Values from an Excel Spreadsheet

    • Reading Individual Cells from an Excel Spreadsheet

    • Copying Data Item Mappings from a Previous Excel Activity (Read)

  17. If necessary, output the modified file to a Data Item.

    Note
    If you do not output the Excel file to a Data Item, it will still be saved and available through SharePoint.

  18. Click OK to close the Properties window.

Related Topics

About the Excel Calculate Activity | Writing Data Item Values to a Column in an Excel Document | Writing Data Item Values to a Row in an Excel Document | Writing Data Item Values to Individual Cells in an Excel Document


Reading a Column of Values from an Excel Spreadsheet

1. Select the Use Data Item option.

2. Click the drop-down list and select the Data Item that will contain the name of the worksheet name from which you want to read.

1. Select Enter name.

The Worksheet name drop-down list changes into a text box.

2. In the text box, enter the name of the worksheet from which you want the activity to read in the text box.

1. Select the Use Data Item option.

2. Click the drop-down list and select the Data Item that contains the label of the column that contains the Data Item XML Tags.

1. Select Enter column.

The Name column drop-down list changes into a text box.

2. In the text box, enter the label of the column that contains the Data Item XML Tags.

1. Select the Use Data Item option.

2. Click the drop-down list and select the Data Item that contains the label of the column that contains the values that you want the activity to read.

1. Select Enter column.

The Value column drop-down list changes into a text box.

2. In the text box, enter the label of the column that contains the values that you want the activity to read.

1. Select the Use Data Item option.

2. Click the drop-down list and select the Data Item that contains the label of the row where you want the activity to start reading.

1. Select Enter row.

The Start row drop-down list changes into a text box.

2. In the text box, enter the label of the row where you want the activity to start reading.

1. Select the Use Data Item option.

2. Click the drop-down list and select the Data Item that contains the label of the row where you want the activity to stop reading.

1. Select Enter row.

The End row drop-down list changes into a text box.

2. In the text box, enter the label of the row where you want the activity to stop reading.

Reading a Column of Values from an Excel Spreadsheet

You can configure the Excel Calculate activity to read information from an entire column in an Excel document and store each cell in a Data Item. Generally, an Excel spreadsheet must be set up specifically for this purpose. One column in the spreadsheet should contain the XML Tags of Data Items, while another column contains the values you want to put in each Data Item. The following table represents two columns that might exist in an Excel spreadsheet.

Flash_Drive_256MB | $19.99
Flash_Drive_512MB | $24.99
Flash_Drive_1GB | $29.99
Flash_Drive_2GB | $39.99
Flash_Drive_4GB | $59.99

The left column contains a list of Data Item names and the right column contains the values that will be placed in those Data Items when the activity runs. The left column is known as the Name column and the right column is known as the Value column. When the activity runs, the values in the Value column are read into the Data Items named in the Name column.

Note:
The Data Item name has to exist in the process for the Data Item to be populated. This activity does not create Data Items at run-time.

To read columns of values into Data Items

  1. Add the Excel Calculate activity to the Canvas and complete the common activity properties.

  2. Click the Excel Calculate tab.

  3. If you have not already done so, select the Excel 2007 file on SharePoint that you want to modify.

  4. If you have not already done so, select the SharePoint URL of the Excel Web Service.

  5. If necessary, configure the activity to write Data Item values to the Excel Document using one of the following methods:

    • Writing Data Item Values to a Column in an Excel Document

    • Writing Data Item Values to a Row in an Excel Document

    • Writing Data Items to Individual Cells in an Excel Document

    • Copying Data Item Mappings from a Previous Excel Activity (Write)

  6. If necessary, configure the activity to calculate the formulas in the workbook using one of the following methods:

    • Calculate the Entire Workbook

    • Calculate only Changes in the Entire Workbook

    • Calculate only Formulas within a Worksheet and Cell Range

  7. Click the Read sub-tab.

  8. Under Automatically map Data Item values, in the Worksheet name field, select the worksheet you want to read in the Excel document using one of the following options:

    • Get the worksheet name from a Data Item

    • Enter the worksheet name at design time

  9. Click the Read values by drop-down list and select Column.

  10. In the Name column field, use one of the following options to select the row in the Excel document that has the XML Tags of the Data Items that you want the activity to populate with values:

    • Get the name column from a Data Item

    • Enter the name column at design-time

  11. In the Value column field, use one of the following options to select the row in the Excel document that has the values that you want the activity to read:

    • Get the value column from a Data Item

    • Enter the value column at design-time

  12. In the Start row field, use one of the following options to select the column at which you want the activity to start reading:

    • Get the start row from a Data Item

    • Enter the start row at design-time

  13. Optional: To set an end row where the activity will stop reading, check the End row check box and use one of the following options:

    • Get the end row from a Data Item

    • Enter the end row at design-time

    Note: If you do not set an end row, the activity will continue reading rows downward until it does not find any more values.

  14. If necessary, output the modified file to a Data Item.

    Note
    If you do not output the Excel file to a Data Item, it will still be saved and available through SharePoint.

  15. Click OK to close the Properties window.

Related Topics

About the Excel Calculate Activity | Reading a Row of Values from an Excel Spreadsheet | Reading Individual Cells from an Excel Spreadsheet | Copying Data Item Mappings from another Excel Activity


Reading a Row of Values from an Excel Spreadsheet

1. Select the Use Data Item option.

2. Click the drop-down list and select the Data Item that will contain the name of the worksheet name from which you want to read.

1. Select Enter name.

The Worksheet name drop-down list changes into a text box.

2. In the text box, enter the name of the worksheet from which you want the activity to read in the text box.

1. Select the Use Data Item option.

2. Click the drop-down list and select the Data Item that contains the label of the row that contains the Data Item XML Tags..

1. Select Enter row.

The Name row drop-down list changes into a text box.

2. In the text box, enter the label of the row that contains the Data Item XML Tags.

1. Select the Use Data Item option.

2. Click the drop-down list and select the Data Item that contains the label of the row that contains the values that you want the activity to read.

1. Select Enter row.

The Value row drop-down list changes into a text box.

2. In the text box, enter the label of the row that contains the values that you want the activity to read.

1. Select the Use Data Item option.

2. Click the drop-down list and select the Data Item that contains the label of the column at which you want the activity to start reading.

1. Select Enter column.

The Start column drop-down list changes into a text box.

2. In the text box, enter the label of the column at which you want the activity to start reading.

1. Select the Use Data Item option.

2. Click the drop-down list and select the Data Item that contains the label of the column at which you want the activity to stop reading.

1. Select Enter column.

The End Column drop-down list changes into a text box.

2. In the text box, enter the label of the column at which you want the activity to stop reading.

Reading a Row of Values from an Excel Spreadsheet

You can configure the Excel Calculate activity to read information from an entire row in an Excel document and store each cell in a Data Item. Generally, an Excel spreadsheet must be set up specifically for this purpose. One row in the spreadsheet should contain the XML Tags of Data Items, while another row contains the values you want to put in each Data Item. The following table represents two rows that might exist in an Excel spreadsheet.

Flash_Drive_256MB | Flash_Drive_512MB | Flash_Drive_1GB | Flash_Drive_2GB | Flash_Drive_4GB
$19.99 | $24.99 | $29.99 | $39.99 | $59.99

The top row contains a list of Data Item names and the bottom row contains the values that will be placed in those Data Items when the activity runs. The top row is known as the Name row and the bottom row is known as the Value row. When the activity runs, the values in the Value row are read into the Data Items named in the Name row.

Note:
The Data Item name has to exist in the process for the Data Item to be populated. This activity does not create Data Items at run-time.

To read rows of values into Data Items

  1. Add the Excel Calculate activity to the Canvas and complete the common activity properties.

  2. Click the Excel Calculate tab.

  3. If you have not already done so, select the Excel 2007 file on SharePoint that you want to modify.

  4. If you have not already done so, select the SharePoint URL of the Excel Web Service.

  5. If necessary, configure the activity to write Data Item values to the Excel Document using one of the following methods:

    • Writing Data Item Values to a Column in an Excel Document

    • Writing Data Item Values to a Row in an Excel Document

    • Writing Data Items to Individual Cells in an Excel Document

    • Copying Data Item Mappings from a Previous Excel Activity (Write)

  6. If necessary, configure the activity to calculate the formulas in the workbook using one of the following methods:

    • Calculate the Entire Workbook

    • Calculate only Changes in the Entire Workbook

    • Calculate only Formulas within a Worksheet and Cell Range

  7. Click the Read sub-tab.

  8. Under Automatically map Data Item values, in the Worksheet name field, select the worksheet you want to read in the Excel document using one of the following options:

    • Get the worksheet name from a Data Item

    • Enter the worksheet name at design time

  9. Click the Read values by drop-down list and select Row.

  10. In the Name row field, use one of the following options to select the row in the Excel document that has the XML Tags of the Data Items that you want the activity to populate with values:

    • Get the name row from a Data Item

    • Enter the name row at design-time

  11. In the Value row field, use one of the following options to select the row in the Excel document that has the values that you want the activity to read:

    • Get the value row from a Data Item

    • Enter the value row at design-time

  12. In the Start column field, use one of the following options to select the column at which you want the activity to start reading:

    • Get the start column from a Data Item

    • Enter the start column at design-time

  13. Optional: To set an end column at which the activity will stop reading, check the End column check box and use one of the following options:

    • Get the end column from a Data Item

    • Enter the end column at design-time

    Note: If you do not set an end column, the activity will continue reading columns to the right until it does not find any more values.

  14. If necessary, output the modified file to a Data Item.

    Note
    If you do not output the Excel file to a Data Item, it will still be saved and available through SharePoint.

  15. Click OK to close the Properties window.

Related Topics

About the Excel 2007 Reader Activity | Reading a Column of Values from an Excel Spreadsheet | Reading Individual Cells from an Excel Spreadsheet | Copying Data Item Mappings from another Excel Activity


Reading Individual Cells from an Excel Spreadsheet

Instead of reading an entire column or row of values to Data Items, you can use the Excel Calculate activity to manually map values in specific cells to Data Items you select.

To manually map Excel values to Data Items

  1. Add the Excel Calculate activity to the Canvas and complete the common activity properties.

  2. Click the Excel Calculate tab.

  3. If you have not already done so, select the Excel 2007 file on SharePoint that you want to modify.

  4. If you have not already done so, select the SharePoint URL of the Excel Web Service.

  5. If necessary, configure the activity to write Data Item values to the Excel Document using one of the following methods:

    • Writing Data Item Values to a Column in an Excel Document

    • Writing Data Item Values to a Row in an Excel Document

    • Writing Data Items to Individual Cells in an Excel Document

    • Copying Data Item Mappings from a Previous Excel Activity (Write)

  6. If necessary, configure the activity to calculate the formulas in the workbook using one of the following methods:

    • Calculate the Entire Workbook

    • Calculate only Changes in the Entire Workbook

    • Calculate only Formulas within a Worksheet and Cell Range

  7. Click the Read sub-tab.

  8. Select Manually map Data Item values.
    The Manually map Data Item values group box is enabled.

  9. Click the Edit Data Item Mappings button.
    The Map Data Items window opens.

    10. Note:
    If a previous Excel activity already contains the Data Item mappings you want to use, you can copy those mappings to this activity.

  10. Click the first drop-down list in the Data Item column and select the Data Item you want to populate.

  11. Click the first drop-down list in the Source column and select whether you want to provide the worksheet name from a Data Item display value, Data Item value, or a constant.

  12. In the Worksheet field, use one of the following methods to specify the worksheet name:

    • If you selected display value or value in the Source column, use the drop-down list to select the Data Item that contains the worksheet name

    • If you selected constant in the Source column, enter the worksheet name into the text box

  13. Click the first drop-down list in the second Source column and select whether you want to provide the cell address from a Data Item display value, Data Item value, or a constant.

  14. In the Cell Address field, use one of the following methods to specify the cell address:

    • If you selected display value or value in the Source column, use the drop-down list to select the Data Item that contains the cell address.

    • If you selected constant in the Source column, enter the cell address into the text box. If the cell has a name, you can enter that instead.

  15. Repeat steps 7-11 to read additional values from the Excel document.

  16. Optional: If you want to read multiple values starting at the Cell address you specified in the table, select the Read multiple values by option and perform one of the following actions:

    • If you want to read all of the subsequent values down the column, select Column from the drop-down list

    • If you want to read all of the subsequent values across the row (to the right), select Row from the drop-down list

    Note:
    Using this option, the activity will continue reading values in the column (or row) until it reaches an empty cell. Every value read will be stored in the corresponding Data Item, meaning that the Data Item will have multiple values mapped to it as instances.

  17. Click OK.
    The Map Data Items window closes.

  18. If necessary, output the modified file to a Data Item.

    Note
    If you do not output the Excel file to a Data Item, it will still be saved and available through SharePoint.

  19. Click OK to close the Properties window.

Related Topics

About the Excel Calculate Activity | Copying Data Item Mappings from a Previous Excel Activity | Reading a Column of Values from an Excel Spreadsheet | Reading a Row of Values from an Excel Spreadsheet


Saving the Excel File to a Data Item

After you write to, calculate, and/or read from an Excel file, those changes are saved to the same Excel file on SharePoint. However, you might want to send that Excel file to a person or use it in some other way as part of the process. In that case, you can save the Excel file to a FilePointer Data Item.

This activity also allows you to define the name of the Excel file that will be stored in the FilePointer Data Item.

To save an Excel File on SharePoint to a Data Item

  1. Add the Excel Calculate activity to the Canvas and complete the common activity properties.

  2. Click the Excel Calculate tab.

  3. If you have not already done so, select the Excel 2007 file on SharePoint that you want to modify.

  4. If you have not already done so, select the SharePoint URL of the Excel Web Service.

  5. If necessary, configure the activity to write Data Item values to the Excel Document using one of the following methods:

    • Writing Data Item Values to a Column in an Excel Document

    • Writing Data Item Values to a Row in an Excel Document

    • Writing Data Items to Individual Cells in an Excel Document

    • Copying Data Item Mappings from a Previous Excel Activity (Write)

  6. If necessary, configure the activity to calculate the formulas in the workbook using one of the following methods:

    • Calculate the Entire Workbook

    • Calculate only Changes in the Entire Workbook

    • Calculate only Formulas within a Worksheet and Cell Range

  7. If necessary, configure the activity to read values from the workbook using one of the following methods:

    • Reading a Row of Values from an Excel Spreadsheet

    • Reading a Column of Values from an Excel Spreadsheet

    • Reading Individual Cells from an Excel Spreadsheet

    • Copying Data Item Mappings from a Previous Excel Activity (Read)

  8. Click the Output to File sub-tab.

  9. Select the Output File to a Data Item option.

  10. Click the Data Item to store output file drop-down list and select the FilePointer Data Item that you want to hold the Excel file.

  11. Click the Edit button next to the Output file name box.
    The Configure Output File Name window appears.


Selecting an Excel 2007 File on SharePoint

You can provide the location of an Excel 2007 file on SharePoint through two methods. You can enter the address to the file when you configure the activity or you can select a Data Item that will contain the Data Item when the process runs.

With either method, you also need to supply SharePoint credentials (user name, password, and possibly domain) in order to access the file.

To Select an Excel file on SharePoint

  1. Add the Excel Calculate activity to the Canvas and complete the common activity properties.

  2. Click the Excel Calculate tab.

  3. Perform one of the two following methods to enter the SharePoint URL of the Excel file.

    • Select the Select Data Item option and then click the drop-down list to select a Data Item that contains the address to the Excel Web Service on SharePoint.

    • Select the Enter URL option and then click the box to enter the address to the Excel Web Service on SharePoint.

  4. If you have not already done so, select the SharePoint URL of the Excel Web Service.

  5. If necessary, configure the activity to write Data Item values to the Excel Document using one of the following methods:

    • Writing Data Item Values to a Column in an Excel Document

    • Writing Data Item Values to a Row in an Excel Document

    • Writing Data Items to Individual Cells in an Excel Document

    • Copying Data Item Mappings from a Previous Excel Activity (Write)

  6. If necessary, configure the activity to calculate the formulas in the workbook using one of the following methods:

    • Calculate the Entire Workbook

    • Calculate only Changes in the Entire Workbook

    • Calculate only Formulas within a Worksheet and Cell Range

  7. If necessary, configure the activity to read values from the workbook using one of the following methods:

    • Reading a Row of Values from an Excel Spreadsheet

    • Reading a Column of Values from an Excel Spreadsheet

    • Reading Individual Cells from an Excel Spreadsheet

    • Copying Data Item Mappings from a Previous Excel Activity (Read)

  8. If necessary, output the modified file to a Data Item.

    Note
    If you do not output the Excel file to a Data Item, it will still be saved and available through SharePoint.

  • Related Topics


Selecting the SharePoint URL of the Excel Web Service

SharePoint 2007 uses an Excel Web service to perform its calculations in Excel. In most circumstances, you can use the Excel Service URL at this address:

http://ServerName/_vti_bin/excelservice.asmx

However, if the Excel document you want to modify is on a custom SharePoint site, you may not have permissions to access the Excel Service at the address given above. Instead, you might need to use the Excel Service URL located at this address:

http://ServerName/CustomSite/_vti_bin/excelservice.asmx

Replace the ServerName placeholder with the actual name of the server and the CustomSite placeholder with the name of the custom SharePoint site.

To Enter the SharePoint URL of the Excel Web Service

  1. Add the Excel Calculate activity to the Canvas and complete the common activity properties.

  2. Click the Excel Calculate tab.

  3. If you have not already done so, select the Excel 2007 file on SharePoint that you want to modify.

  4. Read the text at the beginning of this article to determine what the URL is for the Excel Web Service in your implementation of SharePoint.

  5. Perform one of the two following methods to enter the SharePoint URL of the Excel Web Service.

    • Select the Select Data Item option and then click the drop-down list to select a Data Item that contains the address to the Excel Web Service on SharePoint.

    • Select the Enter URL option and then click the box to enter the address to the Excel Web Service on SharePoint.

  6. If necessary, configure the activity to write Data Item values to the Excel Document using one of the following methods:

    • Writing Data Item Values to a Column in an Excel Document

    • Writing Data Item Values to a Row in an Excel Document

    • Writing Data Items to Individual Cells in an Excel Document

    • Copying Data Item Mappings from a Previous Excel Activity (Write)

  7. If necessary, configure the activity to calculate the formulas in the workbook using one of the following methods:

    • Calculate the Entire Workbook

    • Calculate only Changes in the Entire Workbook

    • Calculate only Formulas within a Worksheet and Cell Range

  8. If necessary, configure the activity to read values from the workbook using one of the following methods:

    • Reading a Row of Values from an Excel Spreadsheet

    • Reading a Column of Values from an Excel Spreadsheet

    • Reading Individual Cells from an Excel Spreadsheet

    • Copying Data Item Mappings from a Previous Excel Activity (Read)

  9. If necessary, output the modified file to a Data Item.

    Note
    If you do not output the Excel file to a Data Item, it will still be saved and available through SharePoint.

  10. Click OK to close the Properties window.


Writing Data Item Values to a Column in an Excel Document

You can use this option in the Excel Calculate activity to write Data Item values to a column in an Excel document.

To Write Data Item values to a Column in an Excel Document

  1. Add the Excel Calculate activity to the Canvas and complete the common activity properties.

  2. Click the Excel Calculate tab.

  3. If you have not already done so, select the Excel 2007 file on SharePoint that you want to modify.

  4. If you have not already done so, select the SharePoint URL of the Excel Web Service.

  5. Click the Write sub-tab.

  6. Select the Enable write option.
    The Auto-fill worksheet with selected Data Items option is selected by default.

  7. Perform one of the following actions to define the name of the worksheet to which you want to write data:

    • Select the Data Item that will contain the name of the worksheet

    • Select the Enter value option and enter the name of the worksheet

  6. Perform one of the following actions to define the coordinates of the cell where the activity should start writing:

    • Select the Data Item that will contain the coordinates of the cell

    • Select the Enter value option and enter the coordinates of the cell

      Note:       Cell coordinates are created by pairing the Excel column letter with the row number. For example, the cell in the upper left corner of every spreadsheet is at the coordinates A1.

  7. Select Column to map Data Item values to the Excel spreadsheet down a column. For example, if you selected cell A1 as your starting position, the Data Items you write to the Excel file will appear in cells A1, A2, A3, A4, and so on.

  8. Click the left and right arrow buttons to move the necessary Data Items from the Available Data Items list to the Data Items list.

  9. Click the up and down arrows to reorder the Data Items in the Data Item list. All Data Items in the Data Items list will appear in that order down the column defined by the cell starting position you selected.

    Note:     You can select Display Value or Value to determine whether the activity will write the display value or the value of the Data Item to the Excel worksheet.

  10. Select the Create Data Item header option if you want to create a header column. If you select this option, the activity will create a header column which will contain the Names of the Data Items you write to the Excel file.

    Note:     The Name of a Data Item is the name you enter when you create a Data Item. It is distinct from the XMLTag of a Data Item.

  11. If necessary, configure the activity to calculate the formulas in the workbook using one of the following methods:

    • Calculate the Entire Workbook

    • Calculate only Changes in the Entire Workbook

    • Calculate only Formulas within a Worksheet and Cell Range

  12. If necessary, configure the activity to read values from the workbook using one of the following methods:

    • Reading a Row of Values from an Excel Spreadsheet

    • Reading a Column of Values from an Excel Spreadsheet

    • Reading Individual Cells from an Excel Spreadsheet

    • Copying Data Item Mappings from a Previous Excel Activity (Read)

  13. If necessary, output the modified file to a Data Item.

    Note
    If you do not output the Excel file to a Data Item, it will still be saved and available through SharePoint.

  14. Click OK to close the Properties window.

Related Topics

About the Excel Calculate Activity | Writing Data Item Values to a Row in an Excel Document | Writing Data Item Values to Individual Cells in an Excel Document


Writing Data Item Values to a Row in an Excel Document

You can use this option in the Excel Calculate activity to write Data Item values to a row in an Excel document.

To Write Data Item values to a Row in an Excel Document

  1. Add the Excel Calculate activity to the Canvas and complete the common activity properties.

  2. Click the Excel Calculate tab.

  3. If you have not already done so, select the Excel 2007 file on SharePoint that you want to modify.

  4. If you have not already done so, select the SharePoint URL of the Excel Web Service.

  5. Click the Write sub-tab.

  6. Select the Enable write option.
    The Auto-fill worksheet with selected Data Items option is selected by default.

  7. Perform one of the following actions to define the name of the worksheet to which you want to write data:

    • Select the Data Item that will contain the name of the worksheet

    • Select the Enter value option and enter the name of the worksheet

      Note:       If you want to write Data Items to a worksheet that does not yet exist, select the Add Worksheet option. The activity will create a new worksheet with the name you define.

  6. Perform one of the following actions to define the coordinates of the cell where the activity should start writing:

    • Select the Data Item that will contain the coordinates of the cell

    • Select the Enter value option and enter the coordinates of the cell

      Note:       Cell coordinates are created by pairing the Excel column letter with the row number. For example, the cell in the upper left corner of every spreadsheet is at the coordinates A1.

  7. Select Row to map Data Item values to the Excel spreadsheet across a row. For example, if you selected cell A1 as your starting position, the Data Items you write to the Excel file will appear in cells A1, B1, C1, D1, and so on.

  8. Click the left and right arrow buttons to move the necessary Data Items from the Available Data Items list to the Data Items list.

  9. Click the up and down arrows to reorder the Data Items in the Data Item list. All Data Items in the Data Items list will appear in that order across the row defined by the cell starting position you selected.

    Note:     You can select Display Value or Value to determine whether the activity will write the display value or the value of the Data Item to the Excel worksheet.

  10. Select the Create Data Item header option if you want to create a header row. If you select this option, the activity will create a header row that will contain the Names of the Data Items you write to the Excel file.

    Note:     The Name of a Data Item is the name you enter when you create a Data Item. It is distinct from the XMLTag of a Data Item.

  11. If necessary, configure the activity to calculate the formulas in the workbook using one of the following methods:

    • Calculate the Entire Workbook

    • Calculate only Changes in the Entire Workbook

    • Calculate only Formulas within a Worksheet and Cell Range

  12. If necessary, configure the activity to read values from the workbook using one of the following methods:

    • Reading a Row of Values from an Excel Spreadsheet

    • Reading a Column of Values from an Excel Spreadsheet

    • Reading Individual Cells from an Excel Spreadsheet

    • Copying Data Item Mappings from a Previous Excel Activity (Read)

  13. If necessary, output the modified file to a Data Item.

    Note
    If you do not output the Excel file to a Data Item, it will still be saved and available through SharePoint.

  14. Click OK to close the Properties window.

Related Topics

About the Excel Calculate Activity | Writing Data Item Values to a Column in an Excel Document | Writing Data Item Values to Individual Cells in an Excel Document


Writing Data Items to Individual Cells in an Excel Document

You can use this option in the Excel Calculate activity to write Data Item values to specific, individual cells in an Excel document.

To Write Data Item values to a Individual Cells in an Excel Document

  1. Add the Excel Calculate activity to the Canvas and complete the common activity properties.

  2. Click the Excel Calculate tab.

  3. If you have not already done so, select the Excel 2007 file on SharePoint that you want to modify.

  4. If you have not already done so, select the SharePoint URL of the Excel Web Service.

  5. Click the Write sub-tab.

  6. Select the Enable write option.

  7. Select the Map selected Data Items to worksheet cells option.
    The Edit Data Item Mappings button becomes enabled.

  8. Click the Edit Data Item Mappings button.
    The Map Data Items window appears.

    Note:     The follow steps describe how to map Data Items to specific cells in an Excel worksheet. If you have already created an Excel Reader or Excel Writer activity in the same process and want to copy the Data Item mappings from that activity, you should use the Copy Data Item Mappings button.

  9. Click the Data Item field and use the drop-down list to select the Data Item that contains a value you want to copy to a cell in an Excel document.

  10. Click the Property field and use the drop-down list to select the property of the Data Item that you want to copy.

    Note:     You will probably use the DisplayValue and Value options most frequently, since those represent that actual data stored in the Data Item. However, if you select Name, the activity will write the name of the Data Item (i.e. the name you typed when you created the Data Item).

  11. Click the Source field next to the Worksheet column. Use the drop-down list to select the source of the information that will define which worksheet you want to write to.

    DisplayValue     is the contents of the Data Item, as it is displayed to the end user (usually the same as the .Value).
    Value     is the contents of the Data Item, as it is used within the BPM Suite system (usually the same as the .DisplayValue).
    Constant     is any value that you type into the field at design time
    InstanceKey     is the value that uniquely identifies the Data Item. In most cases, that is a GUID, but in some cases you may have set the InstanceKey to a more meaningful set of data.

  12. Click the Worksheet field and enter or select the name of the worksheet you want to write to. If you selected Constant in the Source field, you can enter the name of the worksheet. If you selected .DisplayValue, .Value, or InstanceKey, you can click the drop-down list and select the Data Item that will contain the name of the worksheet at run-time.

  13. Click the Source field next to the Cell Address column. Use the drop-down list to select the source of the information that will define which cell you want to write to.

    Note:     For descriptions of the options in the drop-down list, see step 10 above.

  14. Click the Cell Address field and enter or select the address of the cell you want to write to. If you selected Constant in the Source field, you can enter the address of the cell (if the cell has a name, you can enter that instead). If you selected .DisplayValue, .Value, or InstanceKey, you can click the drop-down list and select the Data Item that will contain the address of the cell at run-time.

  15. Select the Write multiple values by option if the Data Items you are writing contain multiple values. The drop-down list becomes enabled, and you can select Row (write multiple values left to right across a row) or Column (write multiple values top to bottom down a column). If the Data Items do not contain multiple values, or if you do not want to write all the values, do not select this option.

  16. Click OK.
    The Map Data Items window closes.

  17. If necessary, configure the activity to calculate the formulas in the workbook using one of the following methods:

    • Calculate the Entire Workbook

    • Calculate only Changes in the Entire Workbook

    • Calculate only Formulas within a Worksheet and Cell Range

  18. If necessary, configure the activity to read values from the workbook using one of the following methods:

    • Reading a Row of Values from an Excel Spreadsheet

    • Reading a Column of Values from an Excel Spreadsheet

    • Reading Individual Cells from an Excel Spreadsheet

    • Copying Data Item Mappings from a Previous Excel Activity (Read)

  19. If necessary, output the modified file to a Data Item.

    Note
    If you do not output the Excel file to a Data Item, it will still be saved and available through SharePoint.

  20. Click OK to close the Properties window.

Related Topics

About the Excel Calculate Activity | Writing Data Item Values to a Column in an Excel Document | Writing Data Item Values to a Row in an Excel Document


About the Excel 2007 Reader Activity

You can use the Excel 2007 Reader activity to copy information from Excel 2007 (.xlsx) documents. You can copy information from cells in the spreadsheet and information in the file properties.

The Excel Reader activity can read information from a file in four kinds of locations:

  • The BPM Suite template directory

  • A networked computer

  • A FilePointer Data Item

  • A SharePoint repository

After you locate the file, you can choose to read the information in one of two ways.

  • Copy an entire row or column of values into a single Data Item

  • Copy individual values to individual Data Items

You might use the first method if you want to copy a row of information from an Excel file that contains employee records. You might use the second method if you want to read the bottom line of an expense report. Rather than read an entire row or column of information in the report, you could copy only the total expense.

Finally, you can use the activity to read values from the file properties. Office 2007 documents have six basic file properties, and you can copy any or all of them to Data Items.

Note:

This activity can read from Excel 2007 files even when Excel 2007 is not installed on the process server. However, it is not able to lock or unlock secure Excel worksheets or protected Excel workbooks.

Follow the links below to view the steps for reading values from Excel documents.

Choosing an Excel document to read

  • Reading from an Excel Document in the Template Directory

  • Reading from an Excel Document in a Network Location

  • Reading from an Excel Document Stored in a FilePointer Data Item

  • Reading from an Excel Document in a SharePoint Repository

Reading values in the Excel document to Data Items

  • Reading a Column of Values from an Excel Spreadsheet

  • Reading a Row of Values from an Excel Spreadsheet

  • Reading Individual Cells from an Excel Spreadsheet

  • Copying Data Item Mappings from a Previous Excel Activity

Reading the File Properties of an Excel document

  • Reading the Properties of an Excel File

Required Auxiliary Topics

Before you begin configuring a Excel 2007 Reader Activity, make sure to complete the following:

  • Create Data Items that will store the Excel information the activity will read


Copying Data Item Mappings from a Previous Excel Activity

Instead of manually mapping each value to a Data Item, you can save time while configuring the Excel 2007 Reader activity by copying the Data Item mappings from a previous Excel activity in the process.

You can copy the Data Item mappings from a previous Excel 2007 Reader OR Excel 2007 Writer activity.

To copy Data Item mappings from another Excel activity

  1. Add the Excel 2007 Reader activity to the Canvas and complete the common activity properties.

  2. Click the Excel 2007 Reader tab.

  3. Configure the activity to read from an Excel document in one of the following four locations:

    • Reading from an Excel Document in the Template Directory

    • Reading from an Excel Document in a Network Location

    • Reading from an Excel Document in a FilePointer Data Item

    • Reading from an Excel Document in a SharePoint Repository

  4. Click the Data Items tab.

  5. Select Manually map Data Item values.
    The Manually map Data Item values group box is enabled.

  6. Click the Edit Data Item Mappings button.
    The Map Data Items window appears.

  7. Click the Copy Data Item Mappings button.
    The Select Prior Excel Activity window appears.

  8. Select a previous Excel activity from which you want to copy the Data Item mappings.

  9. Click OK.
    The Data Item mappings from the Excel activity you selected appear in the table in the Map Data Items window.

  10. Click OK.
    The Map Data Items window closes.

  11. Optionally, click the File Properties tab and select Data Items to contain the file property values.

  12. Click OK.
    The Properties window closes.

Related Topics

About the Excel 2007 Reader Activity | Reading a Column of Values from an Excel Spreadsheet | Reading a Row of Values from an Excel Spreadsheet | Reading Individual Cells from an Excel Spreadsheet


Reading a Column of Values from an Excel Spreadsheet

1. Select the Use Data Item option.

2. Click the drop-down list and select the Data Item that will contain the name of the worksheet name from which you want to read.

1. Select Enter name.

The Worksheet name drop-down list changes into a text box.

2. In the text box, enter the name of the worksheet from which you want the activity to read in the text box.

1. Select the Use Data Item option.

2. Click the drop-down list and select the Data Item that contains the label of the column that contains the Data Item XML Tags.

1. Select Enter column.

The Name column drop-down list changes into a text box.

2. In the text box, enter the label of the column that contains the Data Item XML Tags.

1. Select the Use Data Item option.

2. Click the drop-down list and select the Data Item that contains the label of the column that contains the values that you want the activity to read.

1. Select Enter column.

The Value column drop-down list changes into a text box.

2. In the text box, enter the label of the column that contains the values that you want the activity to read.

1. Select the Use Data Item option.

2. Click the drop-down list and select the Data Item that contains the label of the row where you want the activity to start reading.

1. Select Enter row.

The Start row drop-down list changes into a text box.

2. In the text box, enter the label of the row where you want the activity to start reading.

1. Select the Use Data Item option.

2. Click the drop-down list and select the Data Item that contains the label of the row where you want the activity to stop reading.

1. Select Enter row.

The End row drop-down list changes into a text box.

2. In the text box, enter the label of the row where you want the activity to stop reading.

Reading a Column of Values from an Excel Spreadsheet

You can configure the Excel 2007 Reader activity to read information from an entire column in an Excel document and store each cell in a Data Item. Generally, an Excel spreadsheet must be set up specifically for this purpose. One column in the spreadsheet should contain the XML Tags of Data Items, while another column contains the values you want to put in each Data Item. The following table represents two columns that might exist in an Excel spreadsheet.

Flash_Drive_256MB | $19.99
Flash_Drive_512MB | $24.99
Flash_Drive_1GB | $29.99
Flash_Drive_2GB | $39.99
Flash_Drive_4GB | $59.99

The left column contains a list of Data Item names and the right column contains the values that will be placed in those Data Items when the activity runs. The left column is known as the Name column and the right column is known as the Value column. When the activity runs, the values in the Value column are read into the Data Items named in the Name column.

Note:
The Data Item name has to exist in the process for the Data Item to be populated. This activity does not create Data Items at run-time.

To read columns of values into Data Items

  1. Add the Excel 2007 Reader activity to the Canvas and complete the common activity properties.

  2. Click the Excel 2007 Reader tab.

  3. Configure the activity to get an Excel document to read by using one of the following three methods:

    • Reading from an Excel Document in the Template Directory

    • Reading from an Excel Document in a Network Location

    • Reading from an Excel Document in a FilePointer Data Item

    • Reading from an Excel Document in a SharePoint Repository

  4. Click the Data Items tab.

  5. Under Automatically map Data Item values, in the Worksheet name field, select the worksheet you want to read in the Excel document using one of the following options:

    • Get the worksheet name from a Data Item

    • Enter the worksheet name at design time

  6. Click the Read values by drop-down list and select Column.

  7. In the Name column field, use one of the following options to select the row in the Excel document that has the XML Tags of the Data Items that you want the activity to populate with values:

    • Get the name column from a Data Item

    • Enter the name column at design-time

  8. In the Value column field, use one of the following options to select the row in the Excel document that has the values that you want the activity to read:

    • Get the value column from a Data Item

    • Enter the value column at design-time

  9. In the Start row field, use one of the following options to select the column at which you want the activity to start reading:

    • Get the start row from a Data Item

    • Enter the start row at design-time

  10. Optional: To set an end row where the activity will stop reading, check the End row check box and use one of the following options:

    • Get the end row from a Data Item

    • Enter the end row at design-time

Note: If you do not set an end row, the activity will continue reading rows downward until it does not find any more values.

Related Topics

About the Excel 2007 Reader Activity | Reading a Row of Values from an Excel Spreadsheet | Reading Individual Cells from an Excel Spreadsheet | Copying Data Item Mappings from another Excel Activity


Reading a Row of Values from an Excel Spreadsheet

1. Select the Use Data Item option.

2. Click the drop-down list and select the Data Item that will contain the name of the worksheet name from which you want to read.

1. Select Enter name.

The Worksheet name drop-down list changes into a text box.

2. In the text box, enter the name of the worksheet from which you want the activity to read in the text box.

1. Select the Use Data Item option.

2. Click the drop-down list and select the Data Item that contains the label of the row that contains the Data Item XML Tags..

1. Select Enter row.

The Name row drop-down list changes into a text box.

2. In the text box, enter the label of the row that contains the Data Item XML Tags.

1. Select the Use Data Item option.

2. Click the drop-down list and select the Data Item that contains the label of the row that contains the values that you want the activity to read.

1. Select Enter row.

The Value row drop-down list changes into a text box.

2. In the text box, enter the label of the row that contains the values that you want the activity to read.

1. Select the Use Data Item option.

2. Click the drop-down list and select the Data Item that contains the label of the column at which you want the activity to start reading.

1. Select Enter column.

The Start column drop-down list changes into a text box.

2. In the text box, enter the label of the column at which you want the activity to start reading.

1. Select the Use Data Item option.

2. Click the drop-down list and select the Data Item that contains the label of the column at which you want the activity to stop reading.

1. Select Enter column.

The End Column drop-down list changes into a text box.

2. In the text box, enter the label of the column at which you want the activity to stop reading.

Reading a Row of Values from an Excel Spreadsheet

You can configure the Excel 2007 Reader activity to read information from an entire row in an Excel document and store each cell in a Data Item. Generally, an Excel spreadsheet must be set up specifically for this purpose. One row in the spreadsheet should contain the XML Tags of Data Items, while another row contains the values you want to put in each Data Item. The following table represents two rows that might exist in an Excel spreadsheet.

Flash_Drive_256MB | Flash_Drive_512MB | Flash_Drive_1GB | Flash_Drive_2GB | Flash_Drive_4GB
$19.99 | $24.99 | $29.99 | $39.99 | $59.99

The top row contains a list of Data Item names and the bottom row contains the values that will be placed in those Data Items when the activity runs. The top row is known as the Name row and the bottom row is known as the Value row. When the activity runs, the values in the Value row are read into the Data Items named in the Name row.

Note:
The Data Item name has to exist in the process for the Data Item to be populated. This activity does not create Data Items at run-time.

To read rows of values into Data Items

  1. Add the Excel 2007 Reader activity to the Canvas and complete the common activity properties.

  2. Click the Excel 2007 Reader tab.

  3. Configure the activity to get an Excel document to read by using one of the following three methods:

    • Reading from an Excel Document in the Template Directory

    • Reading from an Excel Document in a Network Location

    • Reading from an Excel Document in a FilePointer Data Item

    • Reading from an Excel Document in a SharePoint Repository

  4. Click the Data Items tab.

  5. Under Automatically map Data Item values, in the Worksheet name field, select the worksheet you want to read in the Excel document using one of the following options:

    • Get the worksheet name from a Data Item

    • Enter the worksheet name at design time

  6. Click the Read values by drop-down list and select Row.

  7. In the Name row field, use one of the following options to select the row in the Excel document that has the XML Tags of the Data Items that you want the activity to populate with values:

    • Get the name row from a Data Item

    • Enter the name row at design-time

  8. In the Value row field, use one of the following options to select the row in the Excel document that has the values that you want the activity to read:

    • Get the value row from a Data Item

    • Enter the value row at design-time

  9. In the Start column field, use one of the following options to select the column at which you want the activity to start reading:

    • Get the start column from a Data Item

    • Enter the start column at design-time

  10. Optional: To set an end column at which the activity will stop reading, check the End column check box and use one of the following options:

    • Get the end column from a Data Item

    • Enter the end column at design-time

Note: If you do not set an end column, the activity will continue reading columns to the right until it does not find any more values.

Related Topics

About the Excel 2007 Reader Activity | Reading a Column of Values from an Excel Spreadsheet | Reading Individual Cells from an Excel Spreadsheet | Copying Data Item Mappings from another Excel Activity


Reading from an Excel Document in a FilePointer Data Item

You can use the Excel 2007 Reader activity to read values from an Excel document stored in a FilePointer Data Item.

Important:
A FilePointer Data Item is a special type of Data Item. You can read more about storing a file in a Data Item.

To read Excel values from an Excel document in a FilePointer Data Item

  1. Add the Excel 2007 Reader activity to the Canvas and complete the common activity properties.

  2. Click the Excel 2007 Reader tab.
    The Input File sub-tab is in front.

  3. Select the FilePointer Data Item option.

  4. Click the drop-down list and select the FilePointer Data Item that will contain the Excel file you want to read.

  5. Click the Data Items tab.

  6. Map values in the Excel Document to Data Items using one of the four following methods:

    • Automatically Mapping Columns of Excel Values to Data Items

    • Automatically Mapping Rows of Excel Values to Data Items

    • Manually Mapping Data from an Excel Document into Data Items

    • Copying Data Item Mappings from another Excel Activity

  7. Optionally, click the File Properties tab and select Data Items to contain the file property values.

  8. Click OK.
    The Properties window closes.

Related Topics

About the Excel 2007 Reader Activity | Reading Excel Values from an Excel Document in a Network Location | Reading Excel Values from an Excel Document Stored in a FilePointer Data Item


Reading from an Excel Document in a Network Location

You can use the Excel 2007 Reader activity to read values from an Excel document stored in a network location.

Important:
The Excel 2007 activity allows you to select any file accessible to you when you design the process; however, the file also needs to be accessible to the process server when the process runs. For the best results, you should enter the path to the file in UNC format (e.g. \\ComputerName\sharedfolder\filename.extension).

To read Excel values from an Excel document in a network location

  1. Add the Excel 2007 Reader activity to the Canvas and complete the common activity properties.

  2. Click the Excel 2007 Reader tab.
    The Input File sub-tab is in front.

  3. Select the Network file option.

  4. Click in the box and enter the UNC path to the file, or click the Browse button and navigate through your network to find the Excel file you want to read.

  5. Click the Data Items tab.

  6. Map values in the Excel Document to Data Items using one of the four following methods:

    • Automatically Mapping Columns of Excel Values to Data Items

    • Automatically Mapping Rows of Excel Values to Data Items

    • Manually Mapping Data from an Excel Document into Data Items

    • Copying Data Item Mappings from another Excel Activity

  7. Optionally, click the File Properties tab and select Data Items to contain the file property values.

  8. Click OK.
    The Properties window closes.

Related Topics

About the Excel 2007 Reader Activity | Reading Excel Values from an Excel Document in a Network Location | Reading Excel Values from an Excel Document Stored in a FilePointer Data Item


Reading from an Excel Document in a SharePoint Repository

You can use the Excel 2007 Reader activity to read values from an Excel document stored in a SharePoint repository.

Important:
You can enter the address to any file on a SharePoint repository; however, you must have sufficient credentials in order to open the file when the activity runs. When you select your SharePoint site credentials, ensure they have the necessary privileges.

To read Excel values from an Excel document in a SharePoint repository

  1. Add the Excel 2007 Reader activity to the Canvas and complete the common activity properties.

  2. Click the Excel 2007 Reader tab.
    The Input File sub-tab is in front.

  3. Select the SharePoint File option.

    • If the entire address to the SharePoint file will be stored in a Data Item, then choose the Select Data Item option.

    • If the address to the SharePoint file will be compiled from multiple Data Items, or if you know the entire address now, then choose the Enter File Path option.

      1. Click the Edit button to open a window that allows you to configure the SharePoint URL.

      2. Click in the URL box to enter the SharePoint URL.

      3. Optionally, click the Data Items drop-down list to select a Data Item that contains part of the SharePoint address, then click the Insert Display Value or Insert Value button to add the Data Item to the URL.

      4. Optionally, click the Preview URL button to see what the URL will look like when the Data Items are replaced with actual values.

      5. Click OK when you are done writing the SharePoint URL.

  4. Select the method by which you wish to specify the SharePoint Server credentials.

    • To use the BPM engine credentials, choose the Use BPM Engine Credentials option, or

    • To manually enter credentials, choose the Enter Credentials option.

      1. Click the Engine Credentials button.

      2. Under the SharePoint username group box:

        • Choose Select Data Item, click the drop-down list, and select the Data Item that will contain the SharePoint username when the process runs, or

        • Choose Enter value and enter the SharePoint username now

      3. Under the SharePoint password group box:

        • Choose Select Data Item, click the drop-down list, and select the Data Item that will contain the SharePoint password when the process runs, or

        • Choose Enter value and enter the SharePoint password now

      4. If your SharePoint site is within a domain, then select the SharePoint Domain check box:

        • Choose Select Data Item, click the drop-down list, and select the Data Item that will contain the SharePoint domain name when the process runs, or

        • Choose Enter value and enter the SharePoint domain name now

      5. Click OK.

  5. Click the Data Items tab.

  6. Map values in the Excel Document to Data Items using one of the four following methods:

    • Automatically Mapping Columns of Excel Values to Data Items

    • Automatically Mapping Rows of Excel Values to Data Items

    • Manually Mapping Data from an Excel Document into Data Items

    • Copying Data Item Mappings from another Excel Activity

  7. Optionally, click the File Properties tab and select Data Items to contain the file property values.

  8. Click OK.
    The Properties window closes.

Related Topics

About the Excel 2007 Reader Activity | Reading Excel Values from an Excel Document in a Network Location | Reading Excel Values from an Excel Document Stored in a FilePointer Data Item


Reading from an Excel Document in the Template Directory

You can use the Excel 2007 Reader activity to read values from an Excel document stored in the Excel Template Directory.

Important:
In order to read from an Excel document in the Template Directory, you must copy the Excel file to that directory on the process server. By default, the Template Directory is located on the BPM Server in C:\Program Files\Bluespring\repository\workflow\template\.

After adding an Excel file to the Template Directory, you need to add the name of the file to the Sys_ExcelTemplates list.

To read Excel values from an Excel document in the Template Directory

  1. Add the Excel 2007 Reader activity to the Canvas and complete the common activity properties.

  2. Click the Excel 2007 Reader tab.
    The Input File sub-tab is in front.

  3. Select the BPM Suite template option.

  4. Click the drop-down list and select the template from which you want to read.
    Note:     The list of templates is based on the Sys_ExcelTemplates list. If you have added a file to the template directory on the server, you also need to add it to the Sys_ExcelTemplates list.

  5. Click the Data Items tab.

  6. Map values in the Excel Document to Data Items using one of the four following methods:

    • Automatically Mapping Columns of Excel Values to Data Items

    • Automatically Mapping Rows of Excel Values to Data Items

    • Manually Mapping Data from an Excel Document into Data Items

    • Copying Data Item Mappings from another Excel Activity

  7. Optionally, click the File Properties tab and select Data Items to contain the file property values.

  8. Click OK.
    The Properties window closes.

Related Topics

About the Excel 2007 Reader Activity | Reading Excel Values from an Excel Document in a Network Location | Reading Excel Values from an Excel Document Stored in a FilePointer Data Item


Reading Individual Cells from an Excel Spreadsheet

Instead of reading an entire column or row of values to Data Items, you can use the Excel 2007 Reader activity to manually map values in specific cells to Data Items you select.

To manually map Excel values to Data Items

  1. Add the Excel 2007 Reader activity to the Canvas and complete the common activity properties.

  2. Click the Excel 2007 Reader tab.

  3. Configure the activity to get an Excel document to read through one of the following four methods:

    • Reading from an Excel Document in the Template Directory

    • Reading from an Excel Document in a Network Location

    • Reading from an Excel Document in a FilePointer Data Item

    • Reading from an Excel Document in a SharePoint Repository

  4. Click the Data Items tab.

  5. Select Manually map Data Item values.
    The Manually map Data Item values group box is enabled.

  6. Click the Edit Data Item Mappings button.
    The Map Data Items window opens.

Note:
If a previous Excel activity already contains the Data Item mappings you want to use, you can copy those mappings to this activity.

  7. Click the first drop-down list in the Data Item column and select the Data Item you want to populate.

  8. Click the first drop-down list in the Source column and select whether you want to provide the worksheet name from a Data Item display value, Data Item value, or a constant.

  9. In the Worksheet field, use one of the following methods to specify the worksheet name:

    • If you selected display value or value in the Source column, use the drop-down list to select the Data Item that contains the worksheet name

    • If you selected constant in the Source column, enter the worksheet name into the text box

  10. Click the first drop-down list in the second Source column and select whether you want to provide the cell address from a Data Item display value, Data Item value, or a constant.

  11. In the Cell Address field, use one of the following methods to specify the cell address:

    • If you selected display value or value in the Source column, use the drop-down list to select the Data Item that contains the cell address.

    • If you selected constant in the Source column, enter the cell address into the text box. If the cell has a name, you can enter that instead.

  12. Repeat steps 7-11 to read additional values from the Excel document.

  13. Optional: If you want to read multiple values starting at the Cell address you specified in the table, select the Read multiple values by option and perform one of the following actions:

    • If you want to read all of the subsequent values down the column, select Column from the drop-down list

    • If you want to read all of the subsequent values across the row (to the right), select Row from the drop-down list

Note:
Using this option, the activity will continue reading values in the column (or row) until it reaches an empty cell. Every value read will be stored in the corresponding Data Item, meaning that the Data Item will have multiple values mapped to it as instances.

  14. Click OK.
    The Map Data Items window closes.

  15. Optionally, click the File Properties tab and select Data Items to contain the file property values.

  16. Click OK.
    the Properties for Activity window closes.

Related Topics

About the Excel 2007 Reader Activity | Copying Data Item Mappings from a Previous Excel Activity | Reading a Column of Values from an Excel Spreadsheet | Reading a Row of Values from an Excel Spreadsheet


Reading the Properties of an Excel File

You can use the Excel 2007 Reader to read the properties of the Excel file into Data Items. The Excel 2007 Reader supports reading the six basic file properties of Excel 2007 documents:

  • Title

  • Subject

  • Author

  • Category

  • Keywords

  • Comments

  1. If you haven't already, select the location of the Excel file that you want to read:

    • BPM Suite Template Directory

    • Network location

    • FilePointer Data Item

    • SharePoint repository

  2. Click the File Properties tab in the Excel 2007 Reader activity properties window.

  3. Click the Value field next to the file property you want to read and select the Data Item that you want to store the file property.

  4. Select Data Items to store all of the file properties that you want to read.

  5. Click OK.
    The Properties window closes.

Related Topics

About the Excel 2007 Reader Activity


About the Excel 2007 Writer Activity

You can use Excel 2007 Writer activity to write information from Data Items to a Microsoft Excel 2007 document. The Excel 2007 Writer can write to an Excel 2007 document located in four kinds of locations:

  • The BPM Suite template directory

  • A networked computer

  • A FilePointer Data Item

  • A SharePoint repository

The activity can write Data Items across a row or down a column, and it can write specific Data Items to specific cells. The activity can also write values to the Excel 2007 document's file properties.

Finally, you can output the Excel 2007 document to a Data Item or to SharePoint. You can define the name of the output file.

Important Considerations

This activity can write to Excel 2007 files even when Excel 2007 is not installed on the process server. However, the activity is not able to lock or unlock secure Excel worksheets or protected Excel workbooks. Also, the activity cannot recalculate the formulas in an Excel spreadsheet after it writes values. To work around this limitation, you could:

  • Select the "Calculate workbook when opened" option when you configure the activity. This will cause all formulas in the spreadsheet to recalculate when the file is opened.

  • Use the Excel Calculate activity, if the Excel file is stored in a SharePoint repository.

Follow the links below to view the steps for writing values to Excel 2007 documents.

Choosing an Excel document to write to

  • Writing to an Excel Document in the Template Directory

  • Writing to an Excel Document in a Network Location

  • Writing to an Excel Document in a FilePointer Data Item

  • Writing to an Excel Document in a SharePoint Repository

Choosing the location of the output file

  • Saving the Excel File to a Data Item

  • Saving the Excel File to a SharePoint Repository

  • Defining the Excel File Name

Writing values in Data Items to the Excel document

  • Writing Data Item Values to a Column in an Excel Document

  • Writing Data Item Values to a Row in an Excel Document

  • Writing Data Item Values to Individual Cells in an Excel Document

  • Copying Data Item Mappings from a Previous Excel Activity

Setting the file properties

  • Writing Data Items to the Excel File Properties

  • Setting the Excel Workbook to Calculate When Opened

  • Setting the Worksheet and Cell Focus

Required Auxiliary Topics

Before you begin configuring a Excel 2007 Writer Activity, make sure to complete the following:

  • Create Data Items that will store the Excel information the activity will write


Copying Data Item Mappings from a Previous Excel Activity

Instead of manually mapping each Data Item to a cell in Excel, you can save time while configuring the Excel 2007 Writer activity by copying the Data Item mappings from a previous Excel activity in the process.

You can copy the Data Item mappings from a previous Excel 2007 Reader, Excel 2007 Writer, or Excel Calculate activity.

To copy Data Item mappings from another Excel activity

  1. Add the Excel 2007 Writer activity to the Canvas and complete the common activity properties.

  2. Click the Excel 2007 Writer tab.

  3. Configure the activity to write to an Excel document in one of the following four locations:

    • Writing to an Excel Document in the Template Directory

    • Writing to an Excel Document in a Network Location

    • Writing to an Excel Document in a FilePointer Data Item

    • Writing to an Excel Document in a SharePoint Repository

  4. Configure the activity to save the Excel document in one of the following two locations:

    • Saving the Excel File to a Data Item

    • Saving the Excel File to a SharePoint Repository

  5. Click the Data Items tab.

  6. Select Map selected Data Items to worksheet cells.
    The group box is enabled.

  7. Click the Edit Data Item Mappings button.
    The Map Data Items window appears.

  8. Click the Copy Data Item Mappings button.
    The Select Prior Excel Activity window appears.

  9. Select a previous Excel activity from which you want to copy the Data Item mappings.

  10. Click OK.
    The Data Item mappings from the Excel activity you selected appear in the table in the Map Data Items window.

  11. Click OK.
    The Map Data Items window closes.

  12. Optionally, click the File Properties tab and select Data Items to contain the file property values.

  13. Click OK.
    The Properties window closes.

Related Topics

About the Excel 2007 Writer Activity | Writing Data Item Values to a Column in an Excel Document | Writing Data Item Values to a Row in an Excel Document | Writing Data Item Values to Individual Cells in an Excel Document


Defining the Excel File Name

After you select where to save an Excel 2007 file (to a Data Item or to SharePoint), you also need to define a name for the file. The Excel file name can be a simple text string or it can be composed of multiple Data Items and/or Non-Data Item values.

To Define the Excel File Name

  1. Add the Excel 2007 Writer activity to the Canvas and complete the common activity properties.

  2. Click the Excel 2007 Writer tab.

  3. If you have not already done so, configure the activity to write to an Excel document based in one of the following four locations:

    • Writing to an Excel 2007 Document in the Template Directory

    • Writing to an Excel 2007 Document in a Network Location

    • Writing to an Excel 2007 Document in a FilePointer Data Item

    • Writing to an Excel 2007 Document in a SharePoint Repository

  4. Click the Output File tab.

  5. If you have not already done so, configure the activity to save the Excel document to one of the following two locations:

    • Saving the Excel File to a Data Item

    • Saving the Excel File to a SharePoint Repository

  6. Click the Edit button next to the Output file name box.
    A window that lets you design the file name appears.

  7. If you want to enter static text as the Excel file name, then click the File name box and enter text.

  8. If you want to include Data Item values in the Excel file name, then select a Data Item in the Available Data Items list and click Insert Display Value or Insert Value.

    Note:     There may be a difference between the Value and the Display Value of a Data Item.

  9. If you want to include a non-Data Item value in the Excel file name, then select one of the options in the Available Non-Data Items list and click Add.

    The File name field shows the final file name with placeholders for all the variables.

  10. Click the Preview File Name button to enter values for the variables and see what the final file name might look like.

  11. Click OK when you're done creating the output file name.

  12. The file name appears in the Output file name field on the Output File tab.

  13. Select the option that corresponds to how you want to handle the Excel file if another file with the same name already exists:

    • Select Overwrite the file if it exists if you want the Excel file to overwrite any other files with the same name in the same location.

    • Select Increment the file name if it exists if you want to add an incrementally higher number to the Excel file name rather than overwrite files with the same name. An incrementally higher file name has a number appended to the end. For example, FileName.xls would become FileName-1.xls, and then FileName-2.xls.

  14. Click the Data Items tab.

  15. Map Data Item values to the Excel document using one of the four following methods:

    • Writing Data Item Values to a Column in an Excel Document

    • Writing Data Item Values to a Row in an Excel Document

    • Writing Data Items to Individual Cells in an Excel Document

    • Copying Data Item Mappings from a Previous Excel Activity

  16. Optionally, click the File Properties tab and set any of the following file properties.

    • Writing Data Items to the Excel File Properties

    • Setting the Excel Workbook to Calculate When Opened

    • Setting the Worksheet and Cell Focus

  17. Click OK.
    The Properties window closes.


Saving the Excel File to a Data Item

You can use the Excel 2007 Writer activity to save an Excel file in two different ways. You can save an Excel file to a FilePointer Data Item or you can save it to a SharePoint repository. You might want to save an Excel file to a Data Item if you plan to manipulate it multiple times throughout a process, or if you do not use SharePoint. You might want to save the file to SharePoint if you want to make the file available to people outside the context of the process and so that SharePoint can maintain a repository of your files.

To save an Excel file to a Data Item

  1. Add the Excel 2007 Writer activity to the Canvas and complete the common activity properties.

  2. Click the Excel 2007 Writer tab.

  3. If you have not already done so, configure the activity to write to an Excel document based in one of the following four locations:

    • Writing to an Excel 2007 Document in the Template Directory

    • Writing to an Excel 2007 Document in a Network Location

    • Writing to an Excel 2007 Document in a FilePointer Data Item

    • Writing to an Excel 2007 Document in a SharePoint Repository

  4. Click the Output File tab.

  5. Select the Output file to a Data Item option.

  6. Click the Data Item to store output file drop-down list and select the FilePointer Data Item that you want to hold the Excel file after the activity writes to it.

    Note:     Only FilePointer Data Items appear in this list.

  7. Define a file name for the Excel file.

  8. Click the Data Items tab.

  9. Map Data Item values to the Excel Document using one of the four following methods:

    • Writing Data Item Values to a Column in an Excel Document

    • Writing Data Item Values to a Row in an Excel Document

    • Writing Data Items to Individual Cells in an Excel Document

    • Copying Data Item Mappings from a Previous Excel Activity

  10. Optionally, click the File Properties tab and set any of the following file properties.

    • Writing Data Items to the Excel File Properties

    • Setting the Excel Workbook to Calculate When Opened

    • Setting the Worksheet and Cell Focus

  11. Click OK.
    The Properties window closes.


Saving the Excel File to a SharePoint Repository

You can use the Excel 2007 Writer activity to save an Excel file in two different ways. You can save an Excel file to a FilePointer Data Item or you can save it to a SharePoint repository. You might want to save an Excel file to a Data Item if you plan to manipulate it multiple times throughout a process, or if you do not use SharePoint. You might want to save the file to SharePoint if you want to make the file available to people outside the context of the process and so that SharePoint can maintain a repository of your files.

To save an Excel file to a SharePoint Repository

  1. Add the Excel 2007 Writer activity to the Canvas and complete the common activity properties.

  2. Click the Excel 2007 Writer tab.

  3. If you have not already done so, configure the activity to write to an Excel document based in one of the following four locations:

    • Writing to an Excel 2007 Document in the Template Directory

    • Writing to an Excel 2007 Document in a Network Location

    • Writing to an Excel 2007 Document in a FilePointer Data Item

    • Writing to an Excel 2007 Document in a SharePoint Repository

  4. Click the Output File tab.

  5. Select the Output file to SharePoint option.

    • If the entire address to the SharePoint file will be stored in a Data Item, then choose the Select Data Item option. Click the drop-down list and select the Data Item that will contain the address to SharePoint location where you want to save the file.

    • If the address to the SharePoint file should be compiled from multiple Data Items, or if you know the entire address now, then choose the Enter file path option.

      1. Click the Edit button to open a window that allows you to configure the SharePoint URL.

      2. Click in the URL box to enter the SharePoint URL.

      3. Optionally, click the Data Items drop-down list to select a Data Item that contains part of the SharePoint address, then click the Insert Display Value or Insert Value button to add the Data Item to the URL.

      4. Optionally, click the Preview URL button to see what the URL will look like when the Data Items are replaced with actual values.

      5. Click OK when you are done writing the SharePoint URL.

  6. If the location on SharePoint where you want to save the file might not already exist when the activity runs, you can select the Create directory if it does not exist option. If you select this option, the Excel 2007 Writer activity will create any directories as necessary to save the file in the specified location.

    Note:     If you do not select this option, and the activity attempts to save a file in a location that does not exist, then the activity will generate an error. The process will still continue.

  7. Click the Enter Credentials button.

  8. Under the SharePoint username group box:

    • Choose Select Data Item, click the drop-down list, and select the Data Item that will contain the SharePoint username when the process runs, or

    • Choose Enter value and enter the SharePoint username now

  9. Under the SharePoint password group box:

    • Choose Select Data Item, click the drop-down list, and select the Data Item that will contain the SharePoint password when the process runs, or

    • Choose Enter value and enter the SharePoint password now

  10. If your SharePoint site is within a domain, then select the SharePoint Domain check box:

    • Choose Select Data Item, click the drop-down list, and select the Data Item that will contain the SharePoint domain name when the process runs, or

    • Choose Enter value and enter the SharePoint domain name now

  11. Click OK.

  12. If you want to save the entire path to the file (including the file name) after it has been saved in SharePoint, you can select the Store the complete file path (including file name) in a Data Item option. After you select that option, the drop-down list will become enabled and you will be able to select the Data Item that you want to contain the complete file path.

  13. Define a file name for the Excel file.

  14. Click the Data Items tab.

  15. Map Data Item values to the Excel Document using one of the four following methods:

    • Writing Data Item Values to a Column in an Excel Document

    • Writing Data Item Values to a Row in an Excel Document

    • Writing Data Items to Individual Cells in an Excel Document

    • Copying Data Item Mappings from a Previous Excel Activity

  16. Optionally, click the File Properties tab and set any of the following file properties.

    • Writing Data Items to the Excel File Properties

    • Setting the Excel Workbook to Calculate When Opened

    • Setting the Worksheet and Cell Focus

  17. Click OK.
    The Properties window closes.


Setting the Excel Workbook to Calculate When Opened

You can use this option in the Excel 2007 Writer activity to force the Excel file to recalculate its formulas when it is opened. When you modify an Excel 2007 file with the Excel 2007 activities in BPM Suite, you might modify a cell that contains values used in a formula. When the Excel 2007 Writer activity modifies a value used in a formula, it does not also update the formula. However, if you enable this option, the formula will be updated as soon as the document is opened.

If you need a formula in the Excel 2007 document to be updated as soon as a cell is changed, you should consider storing the Excel file in a SharePoint repository. In that case, you could use the Excel Calculate activity to read from and write to the file. The Excel Calculate activity uses a feature of SharePoint to update formulas as soon as any relevant data is modified.

To set an Excel Workbook to Calculate When it is Opened

  1. Add the Excel 2007 Writer activity to the Canvas and complete the common activity properties.

  2. Click the Excel 2007 Writer tab.

  3. Click the File Properties tab.

  4. Select the Calculate workbook when opened option.


Setting the Worksheet and Cell Focus

You can use this option in the Excel 2007 Writer activity to define which cell in the workbook will be highlighted when a user opens the file. If you do not select a worksheet and cell here, then the cell that was highlighted when the file was last saved will also be highlighted next time the file is opened. Selecting a worksheet and cell to be highlighted can make it easier for a user to find important information.

To set the Worksheet and Cell Focus

  1. Add the Excel 2007 Writer activity to the Canvas and complete the common activity properties.

  2. Click the Excel 2007 Writer tab.

  3. Click the File Properties tab.

  4. Select the Set worksheet and cell focus option.
    The options inside the group box become available.

  5. Perform one of the following actions to set the worksheet focus for the Excel document:

    • Select the Use Data Item option and click the drop-down list to select the Data Item that contains the name of the worksheet.

    • Select the Enter worksheet option and use the box to type in the name of the worksheet.

  6. Perform one of the following actions to set the cell focus for the Excel document:

    • Select the Use Data Item option and click the drop-down list to select the Data Item that contains the coordinates of the cell.

    • Select the Enter cell address option and use the box to type in the coordinates of the cell.


Writing Data Item Values to a Column in an Excel 2007 Document

You can use this option in the Excel 2007 Writer activity to write Data Item values to a column in an Excel document.

To Write Data Item values to a Column in an Excel Document

  1. Add the Excel 2007 Writer activity to the Canvas and complete the common activity properties.

  2. Click the Excel 2007 Writer tab.

  3. If you have not already done so, configure the activity to write to an Excel document based in one of the following four locations:

    • Writing to an Excel 2007 Document in the Template Directory

    • Writing to an Excel 2007 Document in a Network Location

    • Writing to an Excel 2007 Document in a FilePointer Data Item

    • Writing to an Excel 2007 Document in a SharePoint Repository

  4. If you have not already done so, determine where the completed Excel document will be stored and what its file name will be.

    • Saving the Excel File to a Data Item

    • Saving the Excel File to a SharePoint Repository

    • Defining the Excel File Name

  5. Click the Data Items tab.
    The Auto-fill worksheet with selected Data Items option is selected by default.

  6. Perform one of the following actions to define the name of the worksheet to which you want to write data:

    • Select the Data Item that will contain the name of the worksheet

    • Select the Enter value option and enter the name of the worksheet

      Note:       If you want to write Data Items to a worksheet that does not yet exist, select the Add Worksheet option. The activity will create a new worksheet with the name you define.

  6. Perform one of the following actions to define the coordinates of the cell where the activity should start writing:

    • Select the Data Item that will contain the coordinates of the cell

    • Select the Enter value option and enter the coordinates of the cell

      Note:       Cell coordinates are created by pairing the Excel column letter with the row number. For example, the cell in the upper left corner of every spreadsheet is at the coordinates A1.

  7. Select Column to map Data Item values to the Excel spreadsheet down a column. For example, if you selected cell A1 as your starting position, the Data Items you write to the Excel file will appear in cells A1, A2, A3, A4, and so on.

  8. Determine if you want to overwrite any values that may already be in the column or insert a new column.

    • Select Overwrite existing columns or rows to replace any values that may already be in the column defined by your starting cell position.

    • Select Insert new columns or rows to insert a new column to the left of the column defined by your starting cell position. The values you write to the Excel file will be in the new column.

  9. Click the left and right arrow buttons to move the necessary Data Items from the Available Data Items list to the Data Items list.

  10. Click the up and down arrows to reorder the Data Items in the Data Item list. All Data Items in the Data Items list will appear in that order down the column defined by the cell starting position you selected.

    Note:     You can select Display Value or Value to determine whether the activity will write the display value or the value of the Data Item to the Excel worksheet.

  11. Select the Create Data Item header option if you want to create a header column. If you select this option, the activity will create a header column which will contain the Names of the Data Items you write to the Excel file.

    Note:     The Name of a Data Item is the name you enter when you create a Data Item. It is distinct from the XMLTag of a Data Item.

  12. Optionally, click the File Properties tab and set any of the following file properties.

    • Writing Data Items to the Excel File Properties

    • Setting the Excel Workbook to Calculate When Opened

    • Setting the Worksheet and Cell Focus

  13. Click OK.
    The Properties window closes.

Related Topics

About the Excel 2007 Writer Activity | Writing Data Item Values to a Row in an Excel Document | Writing Data Item Values to Individual Cells in an Excel Document


Writing Data Item Values to a Row in an Excel 2007 Document

  1. Choose the Select Data Item option.

  2. Click the drop-down list and select the Data Item that will contain the name of the worksheet.

  1. Choose the Select Data Item option.

  2. Click the drop-down list and select the Data Item that will contain the coordinates of the cell.

Writing Excel Values to a Row in an Excel 2007 Document

You can use this option in the Excel 2007 Writer activity to write Data Item values to a row in an Excel document.

To Write Data Item values to a Row in an Excel Document

  1. Add the Excel 2007 Writer activity to the Canvas and complete the common activity properties.

  2. Click the Excel 2007 Writer tab.

  3. If you have not already done so, configure the activity to write to an Excel document based in one of the following four locations:

    • Writing to an Excel 2007 Document in the Template Directory

    • Writing to an Excel 2007 Document in a Network Location

    • Writing to an Excel 2007 Document in a FilePointer Data Item

    • Writing to an Excel 2007 Document in a SharePoint Repository

  4. If you have not already done so, determine where the completed Excel document will be stored and what its file name will be.

    • Saving the Excel File to a Data Item

    • Saving the Excel File to a SharePoint Repository

    • Defining the Excel File Name

  5. Click the Data Items tab.
    The Auto-fill worksheet with selected Data Items option is selected by default.

  6. Perform one of the following actions to define the name of the worksheet to which you want to write data:

    • Select the Data Item that will contain the name of the worksheet

    • Select the Enter value option and enter the name of the worksheet

      Note:       If you want to write Data Items to a worksheet that does not yet exist, select the Add Worksheet option. The activity will create a new worksheet with the name you define.

  6. Perform one of the following actions to define the coordinates of the cell where the activity should start writing:

    • Select the Data Item that will contain the coordinates of the cell

    • Select the Enter value option and enter the coordinates of the cell

      Note:       Cell coordinates are created by pairing the Excel column letter with the row number. For example, the cell in the upper left corner of every spreadsheet is at the coordinates A1.

  7. Select Row to map Data Item values to the Excel spreadsheet across a row. For example, if you selected cell A1 as your starting position, the Data Items you write to the Excel file will appear in cells A1, B1, C1, D1, and so on.

  8. Determine if you want to overwrite any values that may already be in the row or insert a new row.

    • Select Overwrite existing columns or rows to replace any values that may already be in the row defined by your starting cell position.

    • Select Insert new columns or rows to insert a new column above the row defined by your starting cell position. The values you write to the Excel file will be in the new row.

  9. Click the left and right arrow buttons to move the necessary Data Items from the Available Data Items list to the Data Items list.

  10. Click the up and down arrows to reorder the Data Items in the Data Item list. All Data Items in the Data Items list will appear in that order across the row defined by the cell starting position you selected.

    Note:     You can select Display Value or Value to determine whether the activity will write the display value or the value of the Data Item to the Excel worksheet.

  11. Select the Create Data Item header option if you want to create a header row. If you select this option, the activity will create a header row that will contain the Names of the Data Items you write to the Excel file.

    Note:     The Name of a Data Item is the name you enter when you create a Data Item. It is distinct from the XMLTag of a Data Item.

  12. Optionally, click the File Properties tab and set any of the following file properties.

    • Writing Data Items to the Excel File Properties

    • Setting the Excel Workbook to Calculate When Opened

    • Setting the Worksheet and Cell Focus

  13. Click OK.
    The Properties window closes.

Related Topics

About the Excel 2007 Writer Activity | Writing Data Item Values to a Column in an Excel Document | Writing Data Item Values to Individual Cells in an Excel Document


Writing Data Item Values to Individual Cells in an Excel 2007 Document

You can use this option in the Excel 2007 Writer activity to write Data Item values to specific, individual cells in an Excel document.

To Write Data Item values to a Individual Cells in an Excel Document

  1. Add the Excel 2007 Writer activity to the Canvas and complete the common activity properties.

  2. Click the Excel 2007 Writer tab.

  3. If you have not already done so, configure the activity to write to an Excel document based in one of the following four locations:

    • Writing to an Excel 2007 Document in the Template Directory

    • Writing to an Excel 2007 Document in a Network Location

    • Writing to an Excel 2007 Document in a FilePointer Data Item

    • Writing to an Excel 2007 Document in a SharePoint Repository

  4. If you have not already done so, determine where the completed Excel document will be stored and what its file name will be.

    • Saving the Excel File to a Data Item

    • Saving the Excel File to a SharePoint Repository

    • Defining the Excel File Name

  5. Click the Data Items tab.

  6. Select the Map selected Data Items to worksheet cells option.
    The Edit Data Item Mappings button becomes enabled.

  7. Click the Edit Data Item Mappings button.
    The Map Data Items window appears.

    Note:     The follow steps describe how to map Data Items to specific cells in an Excel worksheet. If you have already created an Excel Reader or Excel Writer activity in the same process and want to copy the Data Item mappings from that activity, you should use the Copy Data Item Mappings button.

  8. Click the Data Item field and use the drop-down list to select the Data Item that contains a value you want to copy to a cell in an Excel document.

  9. Click the Property field and use the drop-down list to select the property of the Data Item that you want to copy.

    Note:     You will probably use the DisplayValue and Value options most frequently, since those represent that actual data stored in the Data Item. However, if you select Name, the activity will write the name of the Data Item (i.e. the name you typed when you created the Data Item).

  10. Click the Source field next to the Worksheet column. Use the drop-down list to select the source of the information that will define which worksheet you want to write to.

    DisplayValue     is the contents of the Data Item, as it is displayed to the end user (usually the same as the .Value).
    Value     is the contents of the Data Item, as it is used within the BPM Suite system (usually the same as the .DisplayValue).
    Constant     is any value that you type into the field at design time
    InstanceKey     is the value that uniquely identifies the Data Item. In most cases, that is a GUID, but in some cases you may have set the InstanceKey to a more meaningful set of data.

  11. Click the Worksheet field and enter or select the name of the worksheet you want to write to. If you selected Constant in the Source field, you can enter the name of the worksheet (if the cell has a name, you can enter that instead). If you selected .DisplayValue, .Value, or InstanceKey, you can click the drop-down list and select the Data Item that will contain the name of the worksheet at run-time.

  12. Click the Source field next to the Cell Address column. Use the drop-down list to select the source of the information that will define which cell you want to write to.

    Note:     For descriptions of the options in the drop-down list, see step 10 above.

  13. Click the Cell Address field and enter or select the name of the worksheet you want to write to. If you selected Constant in the Source field, you can enter the name of the worksheet. If you selected .DisplayValue, .Value, or InstanceKey, you can click the drop-down list and select the Data Item that will contain the name of the worksheet at run-time.

  14. Select the Write multiple values by option if the Data Items you are writing contain multiple values. The drop-down list becomes enabled, and you can select Row (write multiple values left to right across a row) or Column (write multiple values top to bottom down a column). If the Data Items do not contain multiple values, or if you do not want to write all the values, do not select this option.

  15. Click OK.
    The Map Data Items window closes.

  16. Optionally, click the File Properties tab and set any of the following file properties.

    • Writing Data Items to the Excel File Properties

    • Setting the Excel Workbook to Calculate When Opened

    • Setting the Worksheet and Cell Focus

  17. Click OK.
    The Properties window closes.

Related Topics

About the Excel 2007 Writer Activity | Writing Data Item Values to a Column in an Excel Document | Writing Data Item Values to a Row in an Excel Document


Writing Data Items to the Excel File Properties

You can use this option in the Excel 2007 Writer activity to add metadata information to the properties of the Excel file.

To Write Data Item values to the Excel File Properties

  1. Add the Excel 2007 Writer activity to the Canvas and complete the common activity properties.

  2. Click the Excel 2007 Writer tab.

  3. If you have not already done so, configure the activity to write to an Excel document based in one of the following four locations:

    • Writing to an Excel 2007 Document in the Template Directory

    • Writing to an Excel 2007 Document in a Network Location

    • Writing to an Excel 2007 Document in a FilePointer Data Item

    • Writing to an Excel 2007 Document in a SharePoint Repository

  4. If you have not already done so, determine where the completed Excel document will be stored and what its file name will be.

    • Saving the Excel File to a Data Item

    • Saving the Excel File to a SharePoint Repository

    • Defining the Excel File Name

  5. If you have not already done so, map Data Item information to the Excel document through one of the following methods:

    • Writing Data Item Values to a Column in an Excel 2007 Document

    • Writing Data Item Values to a Row in an Excel 2007 Document

    • Writing Data Item Values to Individual Cells in an Excel 2007 Document

  6. Click the File Properties tab.

  7. Find the file property you want to set, located in the File Property column.

  8. Click the Source cell for that property and select .DisplayValue, .Value, or Constant.

    Select .DisplayValue if you want to use the Display Value of the Data Item.
    Select .Value if you want to use the Value of the Data Item.
    Select Constant if you want to enter the value for the file property now and use the same value every time the activity runs.

    Note:     Please refer to the help page titled Understanding the Difference Between Value and Display Value for more information on how to choose between those two values.

  9. Click the Value cell for that same property. If you selected .Display Value or .Value in the Source cell, then you can select the Data Item that will contain the value you want to write to that file property. However, if you selected Constant, then you can enter the value as text now.

  10. Optionally, you can set the workbook to recalculate its formulas when opened.

  11. Optionally, you can also select which worksheet and cell in the will have the focus (i.e. be highlighted).

  12. Click OK.
    The Properties window closes.


Writing to an Excel 2007 Document in a FilePointer Data Item

You can use the Excel 2007 Writer activity to write Data Item values to an Excel document stored in a FilePointer Data Item. For more information on FilePointer Data Items, refer to the article titled Storing a File in a Data Item.

To write Data Item values to an Excel document in a FilePointer Data Item

  1. Add the Excel 2007 Writer activity to the Canvas and complete the common activity properties.

  2. Click the Excel 2007 Writer tab.
    The Input File sub-tab is in front.

  3. Select the FilePointer Data Item option.

  4. Click the drop-down list and select the FilePointer Data Item that contains the Excel 2007 document you want to modify.

    Note:     Only FilePointer Data Items appear in this list.

  5. Determine where the completed Excel document will be stored and what its file name will be.

    • Saving the Excel File to a Data Item

    • Saving the Excel File to a SharePoint Repository

    • Defining the Excel File Name

  6. Click the Data Items tab.

  7. Map Data Item values to the Excel Document using one of the four following methods:

    • Writing Data Item Values to a Column in an Excel Document

    • Writing Data Item Values to a Row in an Excel Document

    • Writing Data Items to Individual Cells in an Excel Document

    • Copying Data Item Mappings from another Excel Activity

  8. Optionally, click the File Properties tab and set any of the following file properties.

    • Writing Data Items to the Excel File Properties

    • Setting the Excel Workbook to Calculate When Opened

    • Setting the Worksheet and Cell Focus

  9. Click OK.
    The Properties window closes.

Related Topics

About the Excel 2007 Writer Activity | Writing to an Excel 2007 Document in a Network Location | Writing to an Excel 2007 Document in the Template Directory | Writing to an Excel 2007 Document in a SharePoint Repository


Writing to an Excel 2007 Document in a Network Location

You can use the Excel 2007 Writer activity to write Data Item values to an Excel document stored in any accessible location within your network. The file you select must be accessible to the server that hosts BPM Server when the process runs. It is probably easiest to find a file within your network if that file is in a shared directory. Contact your system administrator if you need help setting up a shared directory in Windows.

To write Data Item values to an Excel document in a Network Location

  1. Add the Excel 2007 Writer activity to the Canvas and complete the common activity properties.

  2. Click the Excel 2007 Writer tab.
    The Input File sub-tab is in front.

  3. Select the Network file option.

  4. If you already know the location of the file that you want to write to, you can enter the file path in the text box. If you want to navigate to the file, then click the Browse button to open a window that will show you all the computers on your network. Click OK after you select the file you want to write to.

    Note:     If you enter the path to the file manually, then you should enter it in UNC format. In most situations, the computer you use to design the process is not the same as the server that executes the process, so a local path (such as one that begins with C:\) will point to a different location on different computers.

  5. Click the Output File tab.

  6. Determine where the completed Excel document will be stored and what its file name will be.

    • Saving the Excel File to a Data Item

    • Saving the Excel File to a SharePoint Repository

    • Defining the Excel File Name

  7. Click the Data Items tab.

  8. Map Data Item values to the Excel Document using one of the four following methods:

    • Writing Data Item Values to a Column in an Excel Document

    • Writing Data Item Values to a Row in an Excel Document

    • Writing Data Items to Individual Cells in an Excel Document

    • Copying Data Item Mappings from another Excel Activity

  9. Optionally, click the File Properties tab and set any of the following file properties.

    • Writing Data Items to the Excel File Properties

    • Setting the Excel Workbook to Calculate When Opened

    • Setting the Worksheet and Cell Focus

  10. Click OK.
    The Properties window closes.

Related Topics

About the Excel 2007 Writer Activity | Writing to an Excel 2007 Document in the Template Directory | Writing to an Excel 2007 Document in a FilePointer Data Item | Writing to an Excel 2007 Document in a SharePoint Repository


Writing to an Excel 2007 Document in a SharePoint Repository

You can use the Excel 2007 Writer activity to write Data Item values to an Excel document stored in a SharePoint repository.

Important:
You can enter the address to any file on a SharePoint repository; however, you must have sufficient credentials in order to open the file when the activity runs. When you select your SharePoint site credentials, ensure they have the necessary privileges.

To write Data Item values to an Excel document in a SharePoint Repository

  1. Add the Excel 2007 Writer activity to the Canvas and complete the common activity properties.

  2. Click the Excel 2007 Writer tab.
    The Input File sub-tab is in front.

  3. Select the SharePoint file option.

    • If the entire address to the SharePoint file will be stored in a Data Item, then choose the Select Data Item option. Click the drop-down list and select the Data Item that will contain the address to the file on SharePoint.

    • If the address to the SharePoint file will be compiled from multiple Data Items, or if you know the entire address now, then choose the Enter File Path option.

      1. Click the Edit button to open a window that allows you to configure the SharePoint URL.

      2. Click in the URL box to enter the SharePoint URL.

      3. Optionally, click the Data Items drop-down list to select a Data Item that contains part of the SharePoint address, then click the Insert Display Value or Insert Value button to add the Data Item to the URL.

      4. Optionally, click the Preview URL button to see what the URL will look like when the Data Items are replaced with actual values.

      5. Click OK when you are done writing the SharePoint URL.

  4. Select the method by which you wish to specify the SharePoint Server credentials.

    • To use the BPM engine credentials, choose the Use BPM Engine Credentials option, or

    • To manually enter credentials, choose the Enter Credentials option.

      1. Click the Enter Credentials button.

      2. Under the SharePoint username group box:

        • Choose Select Data Item, click the drop-down list, and select the Data Item that will contain the SharePoint username when the process runs, or

        • Choose Enter value and enter the SharePoint username now

      3. Under the SharePoint password group box:

        • Choose Select Data Item, click the drop-down list, and select the Data Item that will contain the SharePoint password when the process runs, or

        • Choose Enter value and enter the SharePoint password now

      4. If your SharePoint site is within a domain, then select the SharePoint Domain check box:

        • Choose Select Data Item, click the drop-down list, and select the Data Item that will contain the SharePoint domain name when the process runs, or

        • Choose Enter value and enter the SharePoint domain name now

      5. Click OK.

  5. Determine where the completed Excel document will be stored and what its file name will be.

    • Saving the Excel File to a Data Item

    • Saving the Excel File to a SharePoint Repository

    • Defining the Excel File Name

  6. Click the Data Items tab.

  7. Map Data Item values to the Excel Document using one of the four following methods:

    • Writing Data Item Values to a Column in an Excel Document

    • Writing Data Item Values to a Row in an Excel Document

    • Writing Data Items to Individual Cells in an Excel Document

    • Copying Data Item Mappings from another Excel Activity

  8. Optionally, click the File Properties tab and set any of the following file properties.

    • Writing Data Items to the Excel File Properties

    • Setting the Excel Workbook to Calculate When Opened

    • Setting the Worksheet and Cell Focus

  9. Click OK.
    The Properties window closes.

Related Topics

About the Excel 2007 Writer Activity | Writing to an Excel 2007 Document in a Network Location | Writing to an Excel 2007 Document in the Template Directory | Writing to an Excel 2007 Document in a FilePointer Data Item


Writing to an Excel 2007 Document in the Template Directory

You can use the Excel 2007 Writer activity to write Data Item values to an Excel document stored in the Excel Template Directory.

Important:
In order to write to an Excel document in the Template Directory, you must copy the Excel file to that directory on the process server. By default, the Template Directory is located on the BPM Server in C:\Program Files\Bluespring\repository\workflow\template\.

After adding an Excel file to the Template Directory, you need to add the name of the file to the Sys_ExcelTemplates list.

To write Data Item values to an Excel document in the Template Directory

  1. Add the Excel 2007 Writer activity to the Canvas and complete the common activity properties.

  2. Click the Excel 2007 Writer tab.
    The Input File sub-tab is in front.

  3. Select the BPM Suite template option.

  4. Click the drop-down list and select the template to which you want to write.
    Note:     The list of templates is based on the Sys_ExcelTemplates list. If you have added a file to the template directory on the server, you also need to add it to the Sys_Excel Templates list.

  5. Click the Output File tab.

  6. Determine where the completed Excel document will be stored and what its file name will be.

    • Saving the Excel File to a Data Item

    • Saving the Excel File to a SharePoint Repository

    • Defining the Excel File Name

  7. Click the Data Items tab.

  8. Map Data Item values to the Excel Document using one of the four following methods:

    • Writing Data Item Values to a Column in an Excel Document

    • Writing Data Item Values to a Row in an Excel Document

    • Writing Data Items to Individual Cells in an Excel Document

    • Copying Data Item Mappings from another Excel Activity

  9. Optionally, click the File Properties tab and set any of the following file properties.

    • Writing Data Items to the Excel File Properties

    • Setting the Excel Workbook to Calculate When Opened

    • Setting the Worksheet and Cell Focus

  10. Click OK.
    The Properties window closes.

Related Topics

About the Excel 2007 Writer Activity | Writing to an Excel 2007 Document in a Network Location | Writing to an Excel 2007 Document in a FilePointer Data Item | Writing to an Excel 2007 Document in a SharePoint Repository


About the Excel Reader Activity

You can use the Excel Reader activity to copy information from any document that Microsoft Excel can open. For example, it can read from Excel (xls), Extensible Markup Language (xml) Comma Separated Values (csv), and Tab Separated Values (tsv) files.

The Excel Reader activity can read information from a file in three kinds of locations:

  1. The BPM Suite template directory

  2. A networked computer

  3. A FilePointer Data Item

After you locate the file, you can choose to read the information in one of two ways.

  1. Copy an entire row or column of values into a single Data Item

  2. Copy individual values to individual Data Items

You might use the first method if you want to copy a row of information from an Excel file that contains employee records. One row would contain all the information about one employee, and it would all be copied into one Data Item.

You might use the second method if you want to read the bottom line of an expense report. You might not need to read all the information in the report, but only the total expense.

Follow the links below to view the steps for reading values from Excel documents.

Retrieving an Excel document to read

  • Reading Values from an Excel Document in the Template Directory

  • Reading Values from an Excel Document in a Network Location

  • Reading Values from an Excel Document Stored in a FilePointer Data Item

Mapping values in the Excel document to Data Items

  • Automatically Mapping Columns of Excel Values to Data Items

  • Automatically Mapping Rows of Excel Values to Data Items

  • Manually Mapping Excel Values to Data Items

  • Copying Data Item Mappings from another Excel Activity

Reading password-protected Excel documents

  • Opening Protected Excel Workbooks

  • Opening Secure Excel Worksheets

Required Auxiliary Topics

Before you begin configuring a Excel Reader Activity, make sure to complete the following:

  • Create Data Items that will store the Excel information the activity will read


Auto-Mapping a Row/Column of Excel Values to a Row/Column of Data Items

Mapping a Row/Column of Excel Values to a Row/Column of Data Items

If you want to import information from an Excel document automatically, configure the Excel Reader activity to read information from entire rows or columns in an Excel document and store it in Data Items. This option works best when you have a list of name-value pairs (see example).

Name-Value Pair Example:
In the Excel spreadsheets column A, you have product Data Items. In column B, you have prices for those products. This spreadsheet may be called every time the process runs to get the latest prices for each product. If row 1, column A has the Data Item Flash_Drives_250MB and row 1, column B has the value 12.50, then when the process runs, it will populate the Flash_Drives_250MB Data Item with the value 12.50.

Note:
The Data Item name has to exist in the process for the Data Item to be populated. This activity does not create Data Items at run-time.

To auto-map a row/column of values to a row/column of data items

  1. Add the Excel Reader activity to the designer canvas and complete the common activity properties.

  2. Click the Excel Reader tab.

  3. Using the Input File Data Item drop-down list, select the File Pointer Data Type Data Item that points to the Microsoft Excel document from which you want to get information.

  4. Click the Import from Excel Worksheet radio button.
    The table beneath the radio button is replaced by a series of fields and buttons.

  5. By clicking the corresponding radio button, choose either to read from the same column or row.

  6. In the Worksheet Name field, enter the name of the worksheet from which you want to read information.

  7. In the Data Item name column (or row) field, enter the column/row from which to match the Data Item's name.

  8. In the Data Item value column (or row) field, enter the column/row from which to get the Data Item's value.

  9. In the Name/Value start row (or column) field, enter the row with which to start reading.

  10. In the Name/Value end row (or column) field, enter the row/column with which to stop reading.

  11. Click OK.
    The Properties for Activity window closes.

Related topics

About the Excel Reader Activity


Automatically Mapping Columns of Excel Values to Data Items

1. Leave the Use Data Item option selected.

2. Using the drop-down list, select the Data Item containing the worksheet name from which you want the activity to read.

1. Select Enter name.

The Worksheet name drop-down list changes into a text box.

2. In the text box, enter the name of the worksheet from which you want the activity to read in the text box.

1. Leave the Use Data Item option selected.

2. Using the drop-down list, select the Data Item that contains the label of the column that you want the activity to use to determine which Data Items it will store the read values in.

1. Select Enter column.

The Name column drop-down list changes into a text box.

2. In the text box, enter the label of the column that you want the activity to use to determine which Data Items it will store the read values in.

1. Leave the Use Data Item option selected.

2. Using the drop-down list, select the Data Item that contains the label of the column that contains the values that you want the activity to read.

1. Select Enter column.

The Value column drop-down list changes into a text box.

2. In the text box, enter the label of the column that contains the values that you want the activity to read.

1. Leave the Use Data Item option selected.

2. Using the drop-down list, select the Data Item that contains the label of the row at which you want the activity to start reading.

1. Select Enter row.

The Start row drop-down list changes into a text box.

2. In the text box, enter the label of the row at which you want the activity to start reading.

1. Leave the Use Data Item option selected.

2. Using the drop-down list, select the Data Item that contains the label of the row at which you want the activity to stop reading.

1. Select Enter row.

The End Row drop-down list changes into a text box.

2. In the text box, enter the label of the row at which you want the activity to stop reading.

Automatically Mapping Columns of Excel Values to Data Items

You can configure the Excel Reader activity to import information automatically from entire columns in an Excel document and store it in Data Items. This option works best when you have a list of name-value pairs (see example).

Name-Value Pair Example:
In the Excel spreadsheets column A, you have product Data Items. In column B, you have prices for those products. This spreadsheet may be called every time the process runs to get the latest prices for each product. If row 1, column A has the Data Item Flash_Drives_250MB and row 1, column B has the value 12.50, then when the process runs, it will populate the Flash_Drives_250MB Data Item with the value 12.50.

Note:
The Data Item name has to exist in the process for the Data Item to be populated. This activity does not create Data Items at run-time.

To automatically map columns of Excel values to Data Items

  1. Add the Excel Reader activity to the designer canvas and complete the common activity properties.

  2. Click the Excel Reader tab.

  3. Configure the activity to get an Excel document to read by using one of the following three methods:

    • Reading Excel values from an Excel Document in the Template Directory

    • Reading Excel Values from an Excel Document in a Network Location

    • Reading Excel Values from an Excel Document Stored in a FilePointer Data Item

  4. Click the Data Item Mapping tab.

  5. Under Automatically map Data Item values, in the Worksheet name field, select a worksheet to read in the Excel document using one of the following options:

    • Get the worksheet name from a Data Item

    • Enter the worksheet name at design-time

  6. Using the Read values by drop-down list, select Column.

  7. In the Name column field, use one of the following options to select the column in the Excel document that has the XML tags of the Data Items that you want the activity to populate with read values:

    • Get the name column from a Data Item

    • Enter the name column at design-time

  8. In the Value column field, use one of the following options to select the column in the Excel document that has the values that you want the activity to read:

    • Get the value column from a Data Item

    • Enter the value column at design-time

  9. In the Start row field, use one of the following options to select the row at which you want the activity to start reading:

    • Get the start row from a Data Item

    • Enter the start row at design-time

  10. Optional: To set an end row at which the activity will stop reading, check the End row check box and use one of the following options:

    • Get the end row from a Data Item

    • Enter the end row at design-time

Related Topics

About the Excel Reader Activity | Automatically Mapping Rows of Excel Values to Data Items | Manually Mapping Data from an Excel Document into Data Items | Copying Data Item Mappings from another Excel Activity


Automatically Mapping Rows of Excel Values to Data Items

1. Leave the Use Data Item option selected.

2. Using the drop-down list, select the Data Item containing the worksheet name from which you want the activity to read.

1. Select Enter name.

The Worksheet name drop-down list changes into a text box.

2. In the text box, enter the name of the worksheet from which you want the activity to read in the text box.

1. Leave the Use Data Item option selected.

2. Using the drop-down list, select the Data Item that contains the label of the row that you want the activity to use to determine which Data Items it will store the read values in.

1. Select Enter row.

The Name row drop-down list changes into a text box.

2. In the text box, enter the label of the row that you want the activity to use to determine which Data Items it will store the read values in.

1. Leave the Use Data Item option selected.

2. Using the drop-down list, select the Data Item that contains the label of the row that contains the values that you want the activity to read.

1. Select Enter row.

The Value row drop-down list changes into a text box.

2. In the text box, enter the label of the row that contains the values that you want the activity to read.

1. Leave the Use Data Item option selected.

2. Using the drop-down list, select the Data Item that contains the label of the column at which you want the activity to start reading.

1. Select Enter column.

The Start column drop-down list changes into a text box.

2. In the text box, enter the label of the column at which you want the activity to start reading.

1. Leave the Use Data Item option selected.

2. Using the drop-down list, select the Data Item that contains the label of the column at which you want the activity to stop reading.

1. Select Enter column.

The End Column drop-down list changes into a text box.

2. In the text box, enter the label of the column at which you want the activity to stop reading.

Automatically Mapping Rows of Excel Values to Data Items

You can configure the Excel Reader activity to import information automatically from entire rows in an Excel document and store it in Data Items. This option works best when you have a list of name-value pairs (see example).

Name-Value Pair Example:
In the Excel spreadsheets row 1, you have product Data Items. In row B, you have prices for those products. This spreadsheet may be called every time the process runs to get the latest prices for each product. If column A, row 1 has the Data Item Flash_Drives_250MB and column B, row 1 has the value 12.50, then when the process runs, it will populate the Flash_Drives_250MB Data Item with the value 12.50.

Note:
The Data Item name has to exist in the process for the Data Item to be populated. This activity does not create Data Items at run-time.

To automatically map rows of Excel values to Data Items

  1. Add the Excel Reader activity to the designer canvas and complete the common activity properties.

  2. Click the Excel Reader tab.

  3. Configure the activity to get an Excel document to read by using one of the following three methods:

    • Reading Excel values from an Excel Document in the Template Directory

    • Reading Excel Values from an Excel Document in a Network Location

    • Reading Excel Values from an Excel Document Stored in a FilePointer Data Item

  4. Click the Data Item Mapping tab.

  5. Under Automatically map Data Item values, in the Worksheet name field, select a worksheet to read in the Excel document using one of the following options:

    • Get the worksheet name from a Data Item

    • Enter the worksheet name at design-time

  6. Using the Read values by drop-down list, select Row.

  7. In the Name row field, use one of the following options to select the row in the Excel document that has the XML tags of the Data Items that you want the activity to populate with values:

    • Get the name row from a Data Item

    • Enter the name row at design-time

  8. In the Value row field, use one of the following options to select the row in the Excel document that has the values that you want the activity to read:

    • Get the value row from a Data Item

    • Enter the value row at design-time

  9. In the Start column field, use one of the following options to select the column at which you want the activity to start reading:

    • Get the start column from a Data Item

    • Enter the start column at design-time

  10. Optional: To set an end column at which the activity will stop reading, check the End column check box and use one of the following options:

    • Get the end column from a Data Item

    • Enter the end column at design-time

Related Topics

About the Excel Reader Activity | Automatically Mapping Columns of Excel Values to Data Items | Manually Mapping Data from an Excel Document into Data Items | Copying Data Item Mappings from another Excel Activity


Copying Data Item Mappings from another Excel Activity

Instead of manually mapping each value to a Data Item, you can save time while configuring the Excel Reader activity by copying the Data Item mappings from a previous Excel activity in the process.

You can copy the Data Item mappings from a previous Excel Reader OR Excel Writer activity.

To copy Data Item mappings from another Excel activity

  1. Add the Excel Reader activity to the designer canvas and complete the common activity properties.

  2. Click the Excel Reader tab.

  3. Configure the activity to get an Excel document to read through one of the following three methods:

    • Reading Excel values from an Excel Document in the Template Directory

    • Reading Excel Values from an Excel Document in a Network Location

    • Reading Excel Values from an Excel Document Stored in a FilePointer Data Item

  4. Click the Data Item Mapping tab.

  5. Select Manually map Data Item values.
    The Manually map Data Item values group box is enabled.

  6. Click the Edit Data Item Mappings button.
    The Map Data Items window opens.

  7. Click the Copy Data Item Mappings button.
    The Copy Data Item Mappings window opens.

  8. Select a previous Excel activity in the process from which you want to copy the Data Item mappings.

  9. Click OK.
    The Data Item mappings from the Excel activity you selected appear in the table in the Map Data Items window.

Related Topics

About the Excel Reader Activity | Automatically Mapping Columns of Excel Values to Data Items | Automatically Mapping Rows of Excel Values to Data Items | Manually Mapping Excel Values to Data Items |


Manually Mapping Excel Values to Data Items

Instead of automatically mapping entire columns or rows of values to Data Items, you can use the Excel Reader activity to manually map values in specific cells to Data Items you select.

To manually map Excel values to Data Items

  1. Add the Excel Reader activity to the designer canvas and complete the common activity properties.

  2. Click the Excel Reader tab.

  3. Configure the activity to get an Excel document to read through one of the following three methods:

    • Reading Excel values from an Excel Document in the Template Directory

    • Reading Excel Values from an Excel Document in a Network Location

    • Reading Excel Values from an Excel Document Stored in a FilePointer Data Item

  4. Click the Data Item Mapping tab.

  5. Select Manually map Data Item values.
    The Manually map Data Item values group box is enabled.

  6. Click the Edit Data Item Mappings button.
    The Map Data Items window opens.

  7. Using the Data Item drop-down list, in the Data Item column of the table, select the Data Item you want to populate.
    The Data Item appears in the field.

  8. Using the Source drop-down list, in the Source column of the table, select whether you want to get the worksheet name from a Data Item display value, Data Item value, or a constant.

  9. In the Worksheet field, use one of the following methods to specify the worksheet name:

    • If you selected display value or value in the Source column, use the drop-down list to select the Data Item that contains the worksheet name

    • If you selected constant in the Source column, enter the worksheet name into the text box

  10. Using the second Source drop-down list, in the second Source column of the table, select whether you want to get the cell address from a Data Item display value, Data Item value, or a constant.

  11. In the Cell Address field, use one of the following methods to specify the worksheet name:

    • If you selected display value or value in the Source column, use the drop-down list to select the Data Item that contains the cell address.

    • If you selected constant in the Source column, enter the cell address into the text box. If the cell has a name, you can enter that instead.

  12. Repeat steps 7-11 to read additional values from the Excel document.

  13. Optional: If you want to read multiple values starting at the Cell address you specified in the table, check the Read multiple values by checkbox and perform one of the following actions:

    • If you want to read all of the subsequent values in the column, select Column from the drop-down list

    • If you want to read all of the subsequent values in the row, select Row from the drop-down list

Note:
Using this option, the activity will continue reading values in the column (or row) until it reaches an empty cell. Every value read will be stored in the corresponding Data Item, meaning that the Data Item will have multiple values mapped to it as instances.

  14. Click OK.
    the Properties for Activity window closes.

Related Topics

About the Excel Reader Activity | Automatically Mapping Columns of Excel Values to Data Items | Automatically Mapping Rows of Excel Values to Data Items


1. Leave the Use Data Item option selected.

2. Using the drop-down list, select the Data Item containing the password required to open the workbook.

1. Select Enter Password.

The Password required to open workbook drop-down list changes into a text box.

2. In the text box, enter the password required to open the workbook.

Opening Protected Excel Workbooks

To read from a protected Excel workbook, which is an entire Excel file (including all the worksheets within it), you will have to configure the Excel Reader activity to use a password to open the workbook.

To open protected Excel workbooks

  1. Add the Excel Reader activity to the designer canvas and complete the common activity properties.

  2. Click the Excel Reader tab.

  3. Configure the activity to get an Excel document to read by using one of the following three methods:

    • Reading Excel values from an Excel Document in the Template Directory

    • Reading Excel Values from an Excel Document in a Network Location

    • Reading Excel Values from an Excel Document Stored in a FilePointer Data Item

  4. Under Workbook protection and/or worksheet security, click the Password required to open workbook checkbox.
    The field and options below the checkbox become enabled.

  5. In the field, select the password required to open the workbook by following one of the methods below:

    • Get the password from a Data Item

    • Enter the password at design-time

  6. Configure the activity to read values from the Excel document using one of the following methods:

    • Automatically Mapping Columns of Excel Values to Data Items

    • Automatically Mapping Rows of Excel Values to Data Items

    • Manually Mapping Excel Values to Data Items

    • Copying Data Item Mappings from another Excel Activity

  7. Click OK.
    The Properties for Activity window closes.


1. Leave the Use Data Item option selected.

2. Using the drop-down list, select the Data Item containing the password required to open the worksheet.

1. Select Enter Password.

The Password required to open worksheet drop-down list changes into a text box.

2. In the text box, enter the password required to open the worksheet.

Opening Secure Excel Worksheets

To read from a secure Excel worksheet within an Excel document, you will have to configure the Excel Reader activity to use a password to open the worksheet.

To open secure Excel worksheets

  1. Add the Excel Reader activity to the designer canvas and complete the common activity properties.

  2. Click the Excel Reader tab.

  3. Configure the activity to get an Excel document to read by using one of the following three methods:

    • Reading Excel values from an Excel Document in the Template Directory

    • Reading Excel Values from an Excel Document in a Network Location

    • Reading Excel Values from an Excel Document Stored in a FilePointer Data Item

  4. Under Workbook protection and/or worksheet security, click the Password required to read worksheet checkbox.
    The field and options below the checkbox become enabled.

  5. In the field, select the password required to open the worksheet by following one of the methods below:

    • Get the password from a Data Item

    • Enter the password at design-time

  6. Configure the activity to read values from the input Excel document using one of the following methods:

    • Automatically Mapping Columns of Excel Values to Data Items

    • Automatically Mapping Rows of Excel Values to Data Items

    • Manually Mapping Excel Values to Data Items

    • Copying Data Item Mappings from another Excel Activity

  7. Click OK.
    The Properties for Activity window closes.


Reading Excel Values from an Excel Document in a Network Location

The path can be either a URL (http://...) or a network address (\\<computerName>\<folderName>\<fileName>).

Note:
The path must specify a file that is at a network location that BPM Engine can access.

Through the file browse window, search for and select a file. After you select a file, the activity will automatically generate the path necessary to retrieve the file and it will display the path in the field, in the main activity window.

Note:
The file you select must be at a network location that BPM Engine can access.

Reading Values from an Excel Document in a Network Location

If the Excel document you want to read is located on a server or computer that the computer running BPM Engine has access to, you can configure the Excel Reader activity to retrieve the document from that network location.

To read Excel values from an Excel document in a network location

  1. Add the Excel Reader activity to the designer canvas and complete the common activity properties.

  2. Click the Excel Reader tab.

  3. Under Input file source, select the Select input file from other location option.
    The text box and button below the option is enabled.

  4. Specify the network location of the Excel document by performing one of the following actions:

    • Enter the path to the location of the Excel file you want the activity to populate

    • Browse for the path through a browse window

  5. Optional: Complete the necessary configurations detailed below that are needed to open Excel documents with workbook protection and/or worksheet security:

    • Opening Protected Excel Workbooks

    • Opening Secure Excel Worksheets

  6. Click the Data Item Mappings tab.

  7. Map values in the Excel Document to Data Items using one of the following methods:

    • Automatically Mapping Columns of Excel Values to Data Items

    • Automatically Mapping Rows of Excel Values to Data Items

    • Manually Mapping Data from an Excel Document into Data Items

    • Copying Data Item Mappings from another Excel Activity

  8. Click OK.
    The Properties for Activity window closes.

Related Topics

About the Excel Reader Activity | Reading Excel values from an Excel Document in the Template Directory | Reading Excel Values from an Excel Document Stored in a FilePointer Data Item


Reading Excel Values from an Excel Document in the Template Directory

Reading Values from an Excel Document in the Template Directory

With the Excel Reader activity, you can read values from an Excel document stored in the Excel Template Directory.

Important:
Excel templates must be added to and stored in the Remote Server Repository folder, which by default is located on the BPM Server in C:\Program Files\Bluespring\repository\workflow\template\.

After adding a template to the Repository folder, you need to add the name of the file to the Sys_ExcelTemplates list.

To read Excel values from an Excel document in the Template Directory

  1. Add the Excel Reader activity to the designer canvas and complete the common activity properties.

  2. Click the Excel Reader tab.

  3. Under Input file source, using the Select input file from Template directory drop-down list, select a Excel document.

  4. Click the Data Item Mappings tab.

  5. Optional: Complete the necessary configurations detailed below that are needed to open Excel documents with workbook protection and/or worksheet security:

    • Opening Protected Excel Workbooks

    • Opening Secure Excel Worksheets

  6. Map values in the Excel Document to Data Items using one of the four following methods:

    • Automatically Mapping Columns of Excel Values to Data Items

    • Automatically Mapping Rows of Excel Values to Data Items

    • Manually Mapping Data from an Excel Document into Data Items

    • Copying Data Item Mappings from another Excel Activity

  7. Click OK.
    The Properties for Activity window closes.

Related Topics

About the Excel Reader Activity | Reading Excel Values from an Excel Document in a Network Location | Reading Excel Values from an Excel Document Stored in a FilePointer Data Item


Reading Excel Values from an Excel Document Stored in a FilePointer Data Item

Reading Values from an Excel Document Stored in a FilePointer Data Item

If the Excel document you want to read is contained in a FilePointer Data Item, you can configure the Excel Reader activity to retrieve the document from the Data Item.

To read Excel values from an Excel document stored in a FilePointer Data Item

  1. Add the Excel Reader activity to the designer canvas and complete the common activity properties.

  2. Click the Excel Reader tab.

  3. Under Input file source, select the Select input file referenced by a FilePointer Data Item option.
    The drop-down list below the option is enabled.

  4. Using drop-down list, select a FilePointer Data Item that contains an Excel document.

  5. Optional: Complete the necessary configurations detailed below that are needed to open Excel documents with workbook protection and/or worksheet security:

    • Opening Protected Excel Workbooks

    • Opening Secure Excel Worksheets

  6. Click the Data Item Mappings tab.

  7. Map values in the Excel Document to Data Items using one of the following methods:

    • Automatically Mapping Columns of Excel Values to Data Items

    • Automatically Mapping Rows of Excel Values to Data Items

    • Manually Mapping Data from an Excel Document into Data Items

    • Copying Data Item Mappings from another Excel Activity

  8. Click OK.
    The Properties window closes.

Related Topics

About the Excel Reader Activity | Reading Excel Values from an Excel Document in a Network Location | Reading Excel values from an Excel Document in the Template Directory


About the Excel Writer Activity

You can use Excel Writer activity to write information from a Data Item to a Microsoft Excel document template. The Excel Reader activity can read an Excel document located in one of three locations: the Template directory, a network location, or in a FilePointer Data Item. You can also use the activity to write information to an Excel document by automatically filling rows or columns with a Data Item, or by manually mapping specific Data Items to specific cells.

Use the links below to see the steps required to write to an Excel file in the way you need.

Selecting the Excel document to write to

  • Writing Values to an Excel document in the Template Directory

  • Writing Values to an Excel document in a network location

  • Writing Values to an Excel document stored in a FilePointer Data Item

Mapping Data Items to an Excel document

  • Automatically filling a worksheet with selected Data Items

  • Mapping selected Data Items to worksheet cells

  • Copying Data Item mapping settings from another Excel activity

Writing to password-protected Excel documents

  • Writing to a protected Excel workbook

  • Writing to a secure Excel worksheet

Highlighting a specific cell in an Excel document

  • Highlighting specific cells to help a user read an Excel worksheet

Required Auxiliary Topics

In order to use an Excel Writer activity, an Excel Template that will receive the data items you write must be in the Excel template directory.

  • Adding an Excel File to a Template List

Also, you need to create Data Items to store the information that you configure BPM Suite to write to the Excel spreadsheet template.

  • Creating Data Items

Finally, you need to create a FilePointer Data Item to store the name of the new file created by the Excel Writer Activity.

  • Creating a FilePointer Data Item


Adding an Excel File to the Template Directory

Before you can populate an Excel template with Data Items, you must add the template to BPM Designer's Excel Template Directory.

To add an Excel file to a template directory

  1. Make sure that the Excel template is stored in the Remote Server Repository folder, which by default is located on the BPM Server in <drive>:\Program Files\Bluespring Software Inc\WORKFLOW\<file name>.

  2. Access the List Management window.

  3. In the list table, find the Excel Templates list, labeled Sys_ExcelTemplates.

  4. Double-click Sys_ExcelTemplates.
    A list of all current Excel Template file names appears.

  5. Click the first empty field at the bottom of the Value column.
    A cursor appears in the field.

  6. Type the name of the file exactly as it appears in the Remote Server Repository.

    Example:
    Example_Expense_Report_Read_Values.xls

  7. Press the Enter key.
    The Save button in the upper-left hand corner of the window illuminates.

  8. Click the Save button [image].
    The file location of the Excel template is added to the Excel Templates Directory.

  9. Close the List Management window.


Auto-Filling the Worksheet with Selected Data Items

  1. Choose the Select Data Item option.

  2. Click the drop-down list and select the Data Item that will contain the name of the worksheet.

  1. Choose the Select Data Item option.

  2. Click the drop-down list and select the Data Item that will contain the coordinates of the cell.

Automatically Filling the Worksheet with Selected Data Items

You can use this option in the Excel Writer activity to fill in entire rows or columns of information in an Excel document.

To automatically fill a worksheet with Data Items

  1. If you have not already done so, begin configuring the Excel Writer activity based on where the Excel file is located:

    • Writing to an Excel Document in the Template Directory

    • Writing to an Excel Document in a network location

    • Writing to an Excel Document stored in a FilePointer Data Item

  2. Click the Data Items tab.
    The Auto-fill worksheet with selected Data Items option is selected by default.

  3. Perform one of the following actions to define the name of the worksheet to which you want to write data:

    • Select the Data Item that will contain the name of the worksheet

    • Select the Enter value option and enter the name of the worksheet

      Note:       If you want to write Data Items to a worksheet that does not yet exist, select the Add Worksheet option. The activity will create a new worksheet with the name you define.

  6. Perform one of the following actions to define the coordinates of the cell where the activity should start writing:

    • Select the Data Item that will contain the coordinates of the cell

    • Select the Enter value option and enter the coordinates of the cell

      Note:       Cell coordinates are created by pairing the Excel column letter with the row number. For example, the cell in the upper left corner of every spreadsheet is at the coordinates A1.

  7. Select whether you want to map the Data Items to the Excel spreadsheet across a row (select Row) or down a column (select Column). For example, if you select Row, each Data Item you select below will begin a new row in the spreadsheet.

  8. Click the left and right arrow buttons to move the necessary Data Items from the Available Data Items list to the Selected Data Items list. All Data Items in the Selected Data Items list will begin a new row or column (depending on your selection above) in the Excel document.

    Note:     You can select Display Value or Value to determine whether the activity will write the display value or the value of the Data Item to the Excel worksheet.

  9. Click the up and down arrow buttons to reorder the Data Items in the Selected Data Items list. Data Items will be written from top to bottom (if you selected Column) or from left to right (if you selected Row) in the order they appear in this list.

  10. Select the Create Data Item header option if you want to create header rows or columns. If you select this option, the activity will create a header row or column, and the header name will be the AttributeName of the Data Item.

    Note:     The AttributeName of a Data Item is the name you enter when you create a Data Item.

  11. Optionally, click the File Security tab to enable or disable file security.

  12. Optionally, click the Miscellaneous tab to define which cell should have the focus when the file is saved.

  13. Click OK.

Related Topics

About the Excel Reader Activity


Copying Data Item Mapping Settings from Another Excel Activity

Rather than manually map each Data Item to a worksheet and cell, you can import the mapping settings from a prior Excel Reader or Excel Writer activity.

This is useful in a situation such as the following. Suppose you use the Excel Reader activity to read a set of data from an Excel document, then task someone to edit the data, then use the Excel Writer activity to write the changes back to the Excel file. In that sort of situation, you could import the Data Item mappings from the Excel Reader activity to the Excel Writer activity.

To copy Data Item mapping settings from another Excel activity

  1. Add the Excel Writer activity to the designer canvas and complete the common activity properties.

  2. Click the Excel Writer tab.

  3. If you have not already done so, begin configuring the Excel Writer activity based on where the Excel file is located:

    • Writing to an Excel Document in the Template Directory

    • Writing to an Excel Document in a network location

    • Writing to an Excel Document stored in a FilePointer Data Item

  4. Select the Map selected Data Items to worksheet cells option.
    The Edit Data Item Mappings button becomes available.

  5. Click the Edit Data Item Mappings button.
    The Map Data Items window appears.

  6. Click the Copy Data Item Mappings button.
    The Copy Data Item Mappings window opens.

  7. Select a previous Excel activity in the process from which you want to copy the Data Item mappings.

  8. Click OK.
    The Data Item mappings from the Excel activity you selected appear in the table in the Map Data Items window.

    Note: You can change the mappings that you imported.


Highlighting Specific Cells to Help User Read an Excel Worksheet

Highlighting Specific Cells to Help Users Read an Excel Spreadsheet

Excel spreadsheets can contain many worksheets, all potentially filled with dense information. Searching through such data-intensive documents can be a confusing and time consuming task for a user.

To help users quickly and easily find information in large Excel spreadsheet documents, you can highlight the relevant information for the user by worksheet and cell coordinates.

When a user opens the Excel file, the worksheet and cell you define will be selected and easy to identify.

To highlight a specific cell in an Excel spreadsheet

  1. If you have not already done so, begin configuring the Excel Writer activity based on where the Excel file is located:

    • Writing to an Excel Document in the Template Directory

    • Writing to an Excel Document in a network location

    • Writing to an Excel Document stored in a FilePointer Data Item

  2. If you have not already done so, define what data you want to write to the Excel file:

    • Automatically fill a worksheet with selected Data Items

    • Map selected Data Items to worksheet cells

    • Copy Data Item mapping settings from another Excel activity

  3. If necessary, configure the security settings for the Excel Writer activity when writing to the Excel document.

  4. Click the Miscellaneous sub-tab.

  5. Select the Set worksheet and cell focus option.
    The options inside the group box become available.

  6. Perform one of the following actions to set the worksheet focus for the Excel document:

    • Select the Use Data Item option and click the drop-down list to select the Data Item that contains the name of the worksheet.

    • Select the Enter worksheet option and use the box to type in the name of the worksheet.

  7. Perform one of the following actions to set the cell focus for the Excel document:

    • Select the Use Data Item option and click the drop-down list to select the Data Item that contains the coordinates of the cell.

    • Select the Enter cell address option and use the box to type in the coordinates of the cell.

  8. Click OK.
    The Properties window closes.

Related Topics

About the Excel Writer Activity


Mapping Selected Data Items to Worksheet Cells

You can use this option in the Excel Writer activity to fill in specific cells within an Excel spreadsheet by mapping Data Items to them.

To map Data Items to selected worksheet cells

  1. If you have not already done so, begin configuring the Excel Writer activity based on where the Excel file is located:

    • Writing to an Excel Document in the Template Directory

    • Writing to an Excel Document in a network location

    • Writing to an Excel Document stored in a FilePointer Data Item

  2. Click the Data Items tab.

  3. Select the Map selected Data Items to worksheet cells option.
    The Edit Data Item Mappings button becomes available.

  4. Click the Edit Data Item Mappings button.
    The Map Data Items window appears.

    Note:     The follow steps describe how to map Data Items to specific cells in an Excel worksheet. If you have already created an Excel Reader or Excel Writer activity in the same process and want to copy the Data Item mappings from that activity, you should use the Copy Data Item Mappings button.

  5. Click the Data Item field and use the drop-down list to select the Data Item that contains a value you want to copy to a cell in an Excel document.

  6. Click the Property field and use the drop-down list to select the property of the Data Item that you want to copy.

    Note:     You will probably use the .DisplayValue or .Value option most frequently, since those represent that actual data stored in the Data Item. However, if you select Attribute Name, the activity will write the name of the Data Item (i.e. the name you typed when you created the Data Item).

  7. Click the Source field next to the Worksheet column. Use the drop-down list to select the source of the information that will define which worksheet you want to write to.

    .DisplayValue     is the contents of the Data Item, as it is displayed to the end user (usually the same as the .Value).
    .Value     is the contents of the Data Item, as it is used within the BPM Suite system (usually the same as the .DisplayValue).
    Constant     is any value that you type into the field at design time
    InstanceKey     is the value that uniquely identifies the Data Item. In most cases, that is a GUID, but in some cases you may have set the InstanceKey to a more meaningful set of data.

  8. Click the Worksheet field and enter or select the name of the worksheet you want to write to. If you selected Constant in the Source field, you should enter the name of the worksheet (if the cell has a name, you can enter that instead). If you selected .DisplayValue, .Value, or InstanceKey, you should click the drop-down list and select the Data Item that will contain the name of the worksheet at run-time.

  9. Click the Source field next to the Cell Address column. Use the drop-down list to select the source of the information that will define which cell you want to write to.

    Note:     For descriptions of the options in the drop-down list, see step 7 above.

  10. Click the Cell Address field and enter or select the name of the worksheet you want to write to. If you selected Constant in the Source field, you should enter the name of the worksheet. If you selected .DisplayValue, .Value, or InstanceKey, you should click the drop-down list and select the Data Item that will contain the name of the worksheet at run-time.

  11. Select the Write multiple values by option if the Data Items you are writing contain multiple values. The drop-down list becomes enabled, and you can select Row (write multiple values left to right across a row) or Column (write multiple values top to bottom down a column). If the Data Items do not contain multiple values, or if you do not want to write all the values, do not select this option.

  12. Optionally, click the File Security tab to enable or disable file security.

  13. Optionally, click the Miscellaneous tab to define which cell should have the focus when the file is saved.

  14. Click OK.

Related Topics

About the Excel Writer Activity


Securing a Document Created by the Excel Writer Activity

Some Excel spreadsheets may contain sensitive material that only users with the right clearance should view. In this instance, secure the Excel spreadsheet by password protecting it.

To secure a document created with an Excel Writer activity

  1. Configure the Excel Writer activity to either flood Data Items to an entire worksheet or map Data Items to selected cells in a worksheet.

  2. Click the Security tab on the Excel Writer tab.

  3. Select the Protect specific worksheets and/or ranges option.

  4. Click the Advanced button.
    The Custom Protection Settings window opens.

  5. Enter the sheet or sheets to protect.

  6. Click OK.
    The Custom Protection Settings window closes.

  7. Click the Specify protection password check box and either select the Data Item that holds the password or enter one in the field.

  8. Optional: Complete the Workbook Security options by clicking the Unprotect workbook with password on open check box and by clicking the Protect workbook with password on save check box. After clicking each check box, select the Data Item with the password in the respective field or click the Entered Below radio-button and enter the password in the field.

    Note:
    You can click one, both, or neither check box.

  9. Click OK.
    The Properties for Activity window closes.

Related Topics

About the Excel Writer Activity


Writing Data Item Values to an Excel Document in a Network Location

  1. Click the Edit button.
    The Configure Output File Name window appears.

  2. If necessary, select Data Items from the Available Data Items list and click the Insert Display Value or Insert Value button to add the Data Item value to the File name field.

  3. If necessary, select other variables from the Available Non-Data Items list and click the Insert button to add the value to the File name field.

  4. The File name field shows the final file name with placeholders for all the variables.

  5. Click the Preview File Name button to enter values for the variables and see what the final file name might look like.

  6. Click OK when you're done creating the output file name.

  7. The file name appears in the Output file name field.

Writing Data Item Values to an Excel Document in a Network Location

The Excel Writer activity can write Data Item values to Excel documents that are stored in any available location on the network. However, this activity considers the Excel file a template, so it does not update the file directly. Instead, BPM Suite will make a copy of the file and write the values to that copy. The copy is saved to a FilePointer Data Item, which is in the BPM Suite Repository.

To write to an Excel document in a network location

  1. Add the Excel Writer activity to the designer canvas and complete the common activity properties.

  2. Click the Excel Writer tab.
    The Input & Output File Settings sub-tab is in front.

  3. Select the Select template file from other location option.

  4. Click the Browse button and select a file located anywhere on the same network as BPM Suite.

  5. Click the Data Item to store output file drop-down list and select the Data Item that should hold the copy of the Excel file that has the Data Item values written to it.

    Note:     Only FilePointer Data Items appear in this list.

  6. Perform one of the following actions to define the output file name:

    • Enter the output file name in the Output file name field

    • Build an output file name that uses variables

  7. Click the Output file save as type drop-down list and choose the format you want the finished Excel file to have. The output file type can be almost any file type that is available if you choose Save As from the Excel File menu. The file type you select here is used no matter what file extension you used in the output file name.

  8. Choose whether you want the finished Excel file to overwrite any other files with the same name in the BPM Suite Repository (select Overwrite output file if it exists) or add an incrementally higher number to its own file name and save in the same location as the file with the same name (select Increment file name if it exists).

    Note:     An incrementally higher file name has a number appended to the end. For example, FileName.xls would become FileName-1.xls, and then, FileName-2.xls.

  9. Click the Data Items sub-tab and either

    • Automatically fill the worksheet with selected Data Items (e.g. fill an entire column or an entire row)

    • Map selected Data Items to worksheet cells

    • Copy Data Item mapping settings from another Excel activity


Writing Data Item Values to an Excel Document in the Template Directory

  1. Click the Edit button.
    The Configure Output File Name window appears.

  2. If necessary, select Data Items from the Available Data Items list and click the Insert Display Value or Insert Value button to add the Data Item value to the File name field.

  3. If necessary, select other variables from the Available Non-Data Items list and click the Insert button to add the value to the File name field.

  4. The File name field shows the final file name with placeholders for all the variables.

  5. Click the Preview File Name button to enter values for the variables and see what the final file name might look like.

  6. Click OK when you're done creating the output file name.

  7. The file name appears in the Output file name field.

Writing Data Item Values to an Excel Document in the Template Directory

The Excel Writer activity can write Data Item values to Excel documents that are stored in the BPM Suite Template Directory. However, because the Excel file is considered a template, the activity does not update the file directly. Instead, BPM Suite will make a copy of the file and write the values to that copy.

Important:
Excel templates must be added to and stored in the Remote Server Repository folder, which by default is located on the BPM Server in C:\Program Files\Bluespring\repository\workflow\template\.

After adding a template to the Repository folder, you need to add the name of the file to the Sys_ExcelTemplates list.

To write to an Excel document in the Template directory

  1. Add the Excel Writer activity to the designer canvas and complete the common activity properties.

  2. Click the Excel Writer tab.
    The     Input & Output File Settings sub-tab is in front, and the Select template file from Template directory option is in selected.

  3. Click the drop-down list and select the template Excel file to which you want to write.

    Note:     If the template file is not in the drop-down list, see the steps to add an Excel file to the Template directory.

  4. Click the Data Item to store output file drop-down list and select the Data Item that should hold the copy of the Excel file that has the Data Item values written to it.

    Note:     Only FilePointer Data Items appear in this list.

  5. Perform one of the following actions to define the output file name:

    • Enter the output file name in the Output file name field

    • Build an output file name that uses variables

  6. Click the Output file save as type drop-down list and choose the format you want the finished Excel file to have. The output file type can be almost any file type that is available if you choose Save As from the Excel File menu. The file type you select here is used no matter what file extension you used in the output file name.

  7. Choose whether you want the finished Excel file to overwrite any other files with the same name in the BPM Suite Repository (select Overwrite output file if it exists) or add an incrementally higher number to its own file name and save in the same location as the file with the same name (select Increment file name if it exists).

    Note:     An incrementally higher file name has a number appended to the end. For example, FileName.xls would become FileName-1.xls, and then, FileName-2.xls.

  8. Click the Data Items sub-tab and either

    • Automatically fill the worksheet with selected Data Items (e.g. fill an entire column or an entire row)

    • Map selected Data Items to worksheet cells

    • Copy Data Item mapping settings from another Excel activity


Writing Data Item values to an Excel Document stored in a FilePointer Data Item

  1. Click the Edit button.
    The Configure Output File Name window appears.

  2. If necessary, select Data Items from the Available Data Items list and click the Insert Display Value or Insert Value button to add the Data Item value to the File name field.

  3. If necessary, select other variables from the Available Non-Data Items list and click the Insert button to add the value to the File name field.

  4. The File name field shows the final file name with placeholders for all the variables.

  5. Click the Preview File Name button to enter values for the variables and see what the final file name might look like.

  6. Click OK when you're done creating the output file name.

  7. The file name appears in the Output file name field.

Writing Data Item values to an Excel Document stored in a FilePointer Data Item

The Excel Writer activity can write Data Item values to Excel documents that are stored in a FilePointer Data Item. However, this activity considers the Excel file a template, so it does not update the file directly. Instead, BPM Suite will make a copy of the file and write the values to that copy. The copy is saved to a FilePointer Data Item, which is in the BPM Suite Repository.

To write to an Excel document in a network location

  1. Add the Excel Writer activity to the designer canvas and complete the common activity properties.

  2. Click the Excel Writer tab.
    The Input & Output File Settings sub-tab is in front.

  3. Select the Use existing file in a FilePointer Data Item option.

  4. Click the drop-down list and select the FilePointer Data Item that contains the Excel file to which you want to write.

    Note:     Only FilePointer Data Items appear in this list.

  5. The FilePointer Data Item you selected in step 4 is automatically selected again in the Data Item to store output file drop-down list. This means that the activity will write to the Excel file in the FilePointer Data Item and save the changes in the same FilePointer Data Item. You can select a different FilePointer Data Item to contain the saved changes, if you want.

    Note:     Only FilePointer Data Items appear in this list.

  6. Perform one of the following actions to define the output file name:

    • Enter the output file name in the Output file name field

    • Build an output file name that uses variables

      Note:       If you chose to save the Excel file to the same FilePointer Data Item you read from, you are not able to change the output file name. If you need to change the output file name, you should save the Excel file to a different Data Item.

  7. Click the Output file save as type drop-down list and choose the format you want the finished Excel file to have. The output file type can be almost any file type that is available if you choose Save As from the Excel File menu. The file type you select here is used no matter what file extension you used in the output file name.

  8. Choose whether you want the finished Excel file to overwrite any other files with the same name in the BPM Suite Repository (select Overwrite output file if it exists) or add an incrementally higher number to its own file name and save in the same location as the file with the same name (select Increment file name if it exists).

    Note:     An incrementally higher file name has a number appended to the end. For example, FileName.xls would become FileName-1.xls, and then, FileName-2.xls.

  9. Click the Data Items sub-tab and either

    • Automatically fill the worksheet with selected Data Items (e.g. fill an entire column or an entire row)

    • Map selected Data Items to worksheet cells

    • Copy Data Item mapping settings from another Excel activity


Writing to a Protected Excel Workbook

If you need to write to an Excel workbook that has password protection enabled, you can use the Excel Writer activity to unlock and lock the file.

To write to a protected Excel workbook

  1. Add the Excel Writer activity to the Designer canvas and complete the common activity properties.

  2. Click the Excel Writer tab.

  3. If you have not already done so, begin configuring the Excel Writer activity based on where the Excel file is located:

    • Writing to an Excel Document in the Template Directory

    • Writing to an Excel Document in a network location

    • Writing to an Excel Document stored in a FilePointer Data Item

  4. Perform one of the following steps to map Data Item values to the Excel document:

    • Automatically fill the worksheet with selected Data Items (e.g. fill an entire column or an entire row)

    • Map selected Data Items to worksheet cells

    • Copy Data Item mapping settings from another Excel activity

  5. Click the File Security sub-tab.

  6. If you need to unlock the Excel workbook in order to write to it, select the Remove password from workbook when opened option.

  7. Perform one of the two following steps to define the workbook password:

    • Select the Use Data Item option and use the drop-down list to select the Data Item that contains the workbook password

    • Select the Enter password option and enter the workbook password in the field

  8. If you need to lock the Excel workbook after writing to it, select the Assign password to workbook when closed option.

  9. Perform one of the two following steps to define the workbook password:

    • Select the Use Data Item option and use the drop-down list to select the Data Item that contains the workbook password

    • Select the Enter password option and enter the workbook password in the field

  10. Optionally, enable or disable Worksheet protection.

  11. Optionally, click the Miscellaneous sub-tab to define which cell should have the focus when the file is saved.

  12. Click OK.


Writing to a Secure Excel Worksheet

If you need to write to an Excel worksheet that has password protection enabled, you can use the Excel Writer activity to unlock and lock the worksheet.

To write to a protected Excel worksheet

  1. Add the Excel Writer activity to the Designer canvas and complete the common activity properties.

  2. Click the Excel Writer tab.

  3. If you have not already done so, begin configuring the Excel Writer activity based on where the Excel file is located:

    • Writing to an Excel Document in the Template Directory

    • Writing to an Excel Document in a network location

    • Writing to an Excel Document stored in a FilePointer Data Item

  4. Perform one of the following steps to map Data Item values to the Excel document:

    • Automatically fill the worksheet with selected Data Items (e.g. fill an entire column or an entire row)

    • Map selected Data Items to worksheet cells

    • Copy Data Item mapping settings from another Excel activity

  5. Click the File Security sub-tab.

  6. If you need to unlock the Excel worksheet in order to write to it, select the Password to unprotect worksheet option.
    The drop-down list becomes enabled.

  7. Click the drop-down list and select the Data Item that contains the password for the worksheet.

    Note:     The Excel Writer activity assumes that every worksheet has the same password. If you need to use a different password for a different worksheet, you should use a second Excel Writer activity.

  8. Select the protection settings for the worksheet after the Excel Writer activity writes the data.

    • Do not change individual worksheet protection settings is the default selection, and it leaves any existing protection settings as they were before the activity wrote to the Excel document.

    • Save worksheets as unprotected. Override worksheet protection settings. This option will save the worksheet as unprotected, regardless of any protection settings that may already be in place.

    • Save worksheets as protected. Override worksheet protection settings. This option will save the worksheet as protected, even if it was not previously a protected worksheet. Click the drop-down list and select a Data Item that contains the password for the new protection.

    • Protect specific worksheets and/or cell ranges. If you select this option, click the Advanced button and define which worksheets and/or areas of worksheets (defined by cell coordinates) that you want to protect.

  9. Optionally, enable or disable Workbook protection.

  10. Optionally, click the Miscellaneous sub-tab to define which cell should have the focus when the file is saved.

  11. Click OK.


About the File Writer Activity

The File Writer activity allows you to create and edit delimited and fixed width text (.txt) files. A text file is a plain, unformatted file that contains only letters, numbers, or characters.

Delimited and Fixed Width Text Files

A delimited text file is a text file that has its data fields separated by a delimiter character, like a comma, a semicolon, or a space.

A fixed width text file is a text file that has data fields containing a defined number of characters.

For example, if a fixed width text file has a data field with 50 defined characters, it will extend or limit the data field to that character amount. Entering 20 characters of data into it will cause 30 extra spaces to be added, and entering 60 characters will cause 10 to be deleted.

Writing Files Using the File Writer Activity

Follow the links below to view instructions on how to create the text files mentioned above using the File Writer activity.

  • Writing a New Delimited Text File

  • Writing to an Existing Delimited Text File

  • Writing a New Fixed Width Text File

  • Writing to an Existing Fixed Width Text File

Creating a File Using an Example as a Guide

If you need help in organizing a text file, you can use an example file layout as a guide when creating your text file.

  • Creating a File Using an Example as a Guide

Required Auxiliary Topics

To successfully configure a File Writer activity, you need to create Data Items that store the information used to populate the text file as well as FilePointer Data Items that store the file's name.

  • Creating Data Items

  • Creating a FilePointer Data Item


Creating a File Using an Example as a Guide

Some text files you create or edit may be very large and complicated. As a result, it may be difficult for you to keep track of Data Item information as you add it to the text file.

To make creating and editing complicated text files easier, the File Writer activity allows you to use an example text file as a guide. The example text file is similar to a template, in that you can follow and recreate its organization as you work with your current text file.

To create a file using an example as a guide

  1. Add the File Writer Activity to the designer canvas and complete the common activity properties.

  2. Click the File Writer tab.

  3. Click the Load File Example button.
    An Example File Viewer window opens.

  4. Click either the Delimited or Fixed Width radio button, depending upon the document type of the example text file that you will be using.

  5. Using the Row drop-down list, select the row number that you want to use as an example.

  6. If the example file type is Delimited, select the delimiter that the example file uses by clicking the corresponding radio button.

    Note:
    If you do not pick a delimiter that corresponds to the one in the example file, then the file's information will not display properly in the window.

  7. Click the ellipses button to the right of the Example File field.
    A Select the Example File directory window opens.

  8. From the file directory window, find and click the example text file that you want to use.

  9. Click Open.
    The Select the Example File window closes.
    The example file's information populates the table under the Example File Field.

  10. Click OK.
    The Example File Viewer window closes.
    The example file's information populates the table to the right of the Data Items pane.

  11. Using the example file information as a guide for where you should place information, drag and drop Data Items from the Data Items pane to the table cell that contains a corresponding piece of example file data.

The Data Item replaces the example file information that was in the table. Continue dragging and dropping more Data Items to fill out the rest of the table, using the example file information as a guide.

When finished adding Data Items, continue configuring the activity according to if its a delimited or fixed width text file.

Related Topics

About the File Writer Activity


Writing a New Delimited Text File

The File Writer activity allows you to create a new delimited text file. Furthermore, in the event that you attempt to create a text file that you do not know already exists, you can configure the File Writer activity to either overwrite or add to the data in any potential pre-existing text files.

To write a new delimited text file

  1. Add the File Writer activity to the designer canvas and complete the common activity properties.

  2. Click the File Writer tab.

  3. In the Define File Layout tab, click the Delimited radio button.

  4. Under Delimited File Settings, choose a character that will separate the fields in the file by clicking its corresponding radio button.

  5. In the Data Items pane (lower-left corner of the File Writer window), double-click the Data Item that you want to occupy the next position in the file.
    The Data Item appears in the table to the right of the Data Items pane.
    The Data Item appears in the Example field followed by the character you selected above to separate each field.

    Note:
    Use the green arrows to shift a Data Item's position either up or down by selecting a Data Item in the table and clicking the corresponding green arrow.

    Click the red X to remove a selected Data Item from the table.

  6. Repeat Step 5 to add more Data Items to the table.
    Each additional Data Item will occupy a successive position in the table and the example field.

  7. Under the Define Output File tab, click the Create a new file radio button.
    The fields under the radio button illuminate.

  8. Using the first drop-down list under the Create a new file radio button, select a File Pointer Data Item that will store the location of the saved file.

  9. Click the Edit button next to the Output File Name field.
    A Write to Text File window opens.

  10. Using the Write to Text File window, enter a file name or use Data Items to create a file name.

    Note:
    If you use Data Items to create a file name, you can test the name expression by entering values for the Data Items and clicking the Test Expression button.

    Important
    If you check the Append Unique String to Name checkbox, then the activity will create a new text file with a unique name every time it executes.

  11. Click OK.
    The Write to Text File window closes.
    The file name you entered appears in the Output File Name field.

  12. Under Misc. Options, click either the overwrite the existing file or edit the existing file radio button.
    If the file name already exists, the File Writer activity will perform the action you selected.

  13. If you want to insert a row of reference information into the file to make it more easily identifiable, click the Write header row when creating a new file checkbox.

  14. Click OK.
    The Properties for Activity window closes.

Related Topics

About the File Writer Activity


Writing a New Fixed Width Text File

The File Writer activity allows you to create a new fixed width text file. Furthermore, in the event that you attempt to create a text file that you do not know already exists, you can configure the File Writer activity to either overwrite or add to the data in any potential pre-existing text files.

To write a new fixed width text file

  1. Add the File Writer Activity to the designer canvas and complete the common activity properties.

  2. Click the File Writer tab.

  3. In the Define File Layout tab, click the Fixed Width radio button.
    The Fixed File Settings appear under the radio button.

  4. In the Data Items pane (lower-left corner of the File Writer window), double-click the Data Item that you want to occupy the next position in the file.
    A Length window appears.

  5. In the Length window, enter the character length that you want every field to be and click OK.
    The Data Item appears in the table to the right of the Data Items pane. The Data Item appears in the Example field followed by a space filling in the character length that you entered.

    Note:
    Use the green arrows to shift a Data Item's position either up or down by selecting a Data Item in the table and clicking the corresponding green arrow. Click the red X to remove a selected Data Item from the table.

  6. Repeat steps 4-5 to add more fields to the text file.

  7. Under the Define Output File tab, click the Create a new file radio button.
    The fields under the radio button illuminate.

  8. Using the first drop-down list under the Create a New File radio button, select a File Pointer Data Item that will store the location of the saved file.

  9. Click the Edit button next to the Output File Name field.
    A Write to Text File window opens.

  10. Using the Write to Text File window, enter a file name or use Data Items to create a file name.

    Note:
    If you use Data Items to create a file name, you can test the name expression by entering values for the Data Items and clicking the Test Expression button.

    Important
    If you check the Append Unique String to Name checkbox, then the activity will create a new text file with a unique name every time it executes.

  11. Click OK.
    The Write to Text File window closes. The file name you entered appears in the Output File Name field.

  12. Click OK.
    The Properties for Activity window closes.

Related Topics

About the File Writer Activity


Writing to an Existing Delimited Text File

If you know of an existing delimited text file that you want to edit, the File Writer activity allows you to write to the existing text file and choose either to overwrite or add to its data fields.

To write to an existing delimited text file

  1. Add the File Writer activity to the designer canvas and complete the common activity properties.

  2. Click the File Writer tab.

  3. In the Define File Layout tab, click the Delimited radio button.

  4. Under Delimited File Settings, choose a character that will separate the fields in the file by clicking its corresponding radio button.

  5. In the Data Items pane (lower-left corner of the File Writer window), double-click the Data Item that you want to occupy the next position in the file.
    The Data Item appears in the table to the right of the Data Items pane.
    The Data Item appears in the Example field followed by the character you selected above to separate each field.

    Note:
    Use the green arrows to shift a Data Item's position either up or down by selecting a Data Item in the table and clicking the corresponding green arrow.

    Click the red X to remove a selected Data Item from the table.

  6. Repeat Step 5 to add more Data Items to the table.
    Each additional Data Item will occupy a successive position in the table.

  7. Under the Define Output tab, click the Write to an existing file radio button.

  8. Using the drop-down list under the Write to an existing file radio button, select the Data Item that stores the file name of the text file to which you want to write.

  9. Under Misc. Options, click either the overwrite the existing file or edit the existing file radio button.
    The existing file will be either overwritten or edited, according to your selection.

  10. If you want to insert a row of reference information into the file to make it more easily identifiable, click the Write header row when creating a new file checkbox.

  11. Click OK.
    The Properties for Activity window closes.

Related Topics

About the File Writer Activity


Writing to an Existing Fixed Width Text File

If you know of an existing fixed width text file that you want to edit, the File Writer activity allows you to write to the existing text file and choose either to overwrite or add to its data fields.

To write to an existing fixed width text file

  1. Add the File Writer Activity to the designer canvas and complete the common activity properties.

  2. Click the File Writer.

  3. In the Define File Layout tab, click the Fixed Width radio button.
    The Fixed File Settings appear under the radio button.

  4. In the Data Items pane (lower-left corner of the File Writer window), double-click the Data Item that you want to occupy the next position in the file.
    A Length window appears.

  5. In the Length window, enter the character length that you want every field to be and click OK.
    The Data Item appears in the table to the right of the Data Items pane.
    The Data Item appears in the Example field followed by a space filling in the character length that you entered.

    Note:
    Use the green arrows to shift a Data Item's position either up or down by selecting a Data Item in the table and clicking the corresponding green arrow.

    Click the red X to remove a selected Data Item from the table.

  6. Repeat steps 4-5 to add more fields to the text file.

  7. Under the Define Output tab, click the Write to an existing file radio button.

  8. Using the drop-down list under the Write to an existing file radio button, select the Data Item that stores the file name of the text file to which you want to write.

  9. Under Misc. Options, click either the overwrite the existing file or edit the existing file radio button.
    The existing file will be either overwritten or edited, according to your selection.

  10. If you want to insert a row of reference information into the file to make it more easily identifiable, click the Write header row when creating a new file checkbox.

  11. Click OK.
    The Properties for Activity window closes.

Related Topics

About the File Writer Activity


About the InfoPath 2007 Form Reader Activity

The InfoPath 2007 Form Reader activity allows you to copy information from InfoPath 2007 form fields to Data Items. In order to read from an InfoPath form, you need two files.

  1. The InfoPath template that was filled out. This file will have a .xsn file extension.

  2. The XML file that contains the actual form data that the user entered. This file will have a .xml file extension.

The InfoPath 2007 Form reader activity needs to access the .xsn file while you configure the activity so it knows which fields exist in the form. However, when the activity runs, it will read the information in the .xml file.

Choosing an InfoPath Document to Read

The InfoPath document you read can be stored in any one of four possible locations.

  • Reading from an InfoPath Form in the Template Directory

  • Reading from an InfoPath Form in a Network Location

  • Reading from an InfoPath Form in a FilePointer Data Item

  • Reading from an InfoPath Form in a SharePoint Repository

Setting up Mappings between Form Fields and Data Items

You need to select the InfoPath template file and map its form fields to Data Items.

  • Selecting the InfoPath Template File

  • Mapping Individual InfoPath Form Fields to Data Items

  • Automatically Mapping InfoPath Form Fields to Data Items

  • Copying Data Item Mappings from a Previous InfoPath Activity

Required Auxiliary Topics

Before you begin configuring an InfoPath 2007 Form Reader activity, make sure to complete the following:

  • Create Data Items that will store the form information the activity will read


Automatically Mapping InfoPath Form Fields to Data Items

You can map InfoPath form fields to Data Items in three ways. First, you can map individual form fields with individual Data Items. Second, you can automatically map form fields to Data Items all at once, as long as those Data Items have the same name as the form fields. Finally, you can copy Data Item mappings from a previous InfoPath activity.

This article describes the second method of mapping InfoPath Form Fields to Data Items. In order to use this method, you must create Data Items that have the same names as the InfoPath form fields. For example, if the InfoPath template has a form field named additionalInfo, you would need to create a Data item with the name additionalInfo.

To Automatically Map InfoPath Form Fields to Data Items

  1. If you have not already done so, configure the activity to read from an InfoPath document in one of the following locations:

    • Reading from an InfoPath 2007 Form in the Template Directory

    • Reading from an InfoPath 2007 Form in a Network Location

    • Reading from an InfoPath 2007 Form in a FilePointer Data Item

    • Reading from an InfoPath 2007 Form in a SharePoint Repository

  2. Click the Data Item Mapping tab.

  3. If you have not already done so, select the InfoPath template file.

  4. If you have not already done so, create Data Items with names that match the InfoPath form field names. See the text at the beginning of this article for an example.

  5. Click the Map All button.
    All form fields that match Data Items are automatically mapped and added to the Data mapping selections list. Mapped Data Items are removed from the Data Items list.

  6. Optionally, click the Remove Selected or Remove All buttons to remove any data mappings you do not need.

  7. Click OK.
    The Properties window closes.

Related Topics

About the InfoPath 2007 Form Reader Activity | Mapping Individual InfoPath Form Fields to Data Items | Copying Data Item Mappings from a Previous InfoPath Activity


Copying Data Item Mappings from a Previous InfoPath Activity

You can map InfoPath form fields to Data Items in three ways. First, you can map individual form fields with individual Data Items. Second, you can automatically map form fields to Data Items all at once, as long as those Data Items have the same name as the form fields. Finally, you can copy Data Item mappings from a previous InfoPath activity.

This article describes the third method of mapping InfoPath Form Fields to Data Items. In order to use this method, you must have already configured an InfoPath activity, including setting up the Data Item mappings.

To Copy Data Item Mappings from a Previous InfoPath Activity

  1. If you have not already done so, configure the activity to read from an InfoPath document in one of the following locations:

    • Reading from an InfoPath 2007 Form in the Template Directory

    • Reading from an InfoPath 2007 Form in a Network Location

    • Reading from an InfoPath 2007 Form in a FilePointer Data Item

    • Reading from an InfoPath 2007 Form in a SharePoint Repository

  2. Click the Data Item Mapping tab.

  3. If you have not already done so, select the InfoPath template file.

  4. Click the Copy Data Item Mappings button.
    A list of previous InfoPath activities appears.

  5. Select the InfoPath activity whose mappings you want to copy and click OK.
    The     Data mapping selections list shows the mappings you copied from the previous activity.

  6. Optionally, click the Remove Selected or Remove All buttons to remove any data mappings you do not need.

  7. Click OK.
    The Properties window closes.

Related Topics

About the InfoPath 2007 Form Reader Activity | Mapping Individual InfoPath Form Fields to Data Items | Automatically Mapping InfoPath Form Fields to Data Items


Mapping Individual InfoPath Form Fields to Data Items

You can map InfoPath form fields to Data Items in three ways. First, you can map individual form fields with individual Data Items. Second, you can automatically map form fields to Data Items all at once, as long as those Data Items have the same name as the form fields. Finally, you can copy Data Item mappings from a previous InfoPath activity.

This article describes the first method of mapping InfoPath Form Fields to Data Items.

To Map Individual InfoPath Form Fields to Data Items

  1. If you have not already done so, configure the activity to read from an InfoPath document in one of the following locations:

    • Reading from an InfoPath 2007 Form in the Template Directory

    • Reading from an InfoPath 2007 Form in a Network Location

    • Reading from an InfoPath 2007 Form in a FilePointer Data Item

    • Reading from an InfoPath 2007 Form in a SharePoint Repository

  2. Click the Data Item Mapping tab.

  3. If you have not already done so, select the InfoPath template file.

  4. Select an InfoPath form field in the Form fields list and select a Data Item in the Data Items list.

  5. Click the Map button.
    The Data Item is removed from the Data Items list and the mapping is added to the Data mapping selections list.

  6. Repeat steps 4-5 to map as many form fields and Data Items as necessary.

  7. Optionally, click the Remove Selected or Remove All buttons to remove any data mappings you do not need.

  8. Click OK.
    The Properties window closes.

Related Topics

About the InfoPath 2007 Form Reader Activity | Automatically mapping InfoPath Form Fields to Data Items | Copying Data Item Mappings from a Previous InfoPath Activity


Reading from an InfoPath Form in a FilePointer Data Item

You can use the InfoPath 2007 Form Reader activity to read text and other information from an InfoPath document stored in a FilePointer Data Item.

Important:
A FilePointer Data Item is a special type of Data Item. You can read more about storing a file in a Data Item.

To read information from an InfoPath document in a FilePointer Data Item

  1. Add the InfoPath 2007 Form Reader activity to the Canvas and complete the common activity properties.

  2. Click the InfoPath 2007 Form Reader tab.
    The Input File sub-tab is in front.

  3. Select the FilePointer Data Item option.

  4. Click the drop-down list and select the FilePointer Data Item that will contain the InfoPath file you want to read.

    Note:
    This Data Item should contain the .xml file that stores the completed form. It should not be the uncompleted InfoPath template.

  5. Click the Data Item Mapping tab and select the InfoPath template.

  6. Map the InfoPath form fields to Data Items through one of the following methods:

    • Mapping InfoPath Form Fields to Data Items

    • Automatically Mapping InfoPath Form Fields to Data Items

    • Copying Data Item Mappings from a Previous InfoPath Activity

  7. Click OK.
    The Properties window closes.

Related Topics

About the InfoPath 2007 Form Reader Activity | Reading from an InfoPath 2007 Document in the Template Directory | Reading from an InfoPath 2007 Document in a Network Location | Reading from an InfoPath 2007 Document Stored in a SharePoint Repository


Reading from an InfoPath Form in a Network Location

You can use the InfoPath 2007 Form Reader activity to read text and other information from an InfoPath file stored in a network location.

Important:
The InfoPath 2007 Form Reader activity allows you to select any file accessible to you when you design the process; however, the file also needs to be accessible to the process server when the process runs. For the best results, you should enter the path to the file in UNC format (e.g. \\ComputerName\sharedfolder\filename.extension).

To Read Information from an InfoPath Document in a Network Location

  1. Add the InfoPath 2007 Form Reader activity to the Canvas and complete the common activity properties.

  2. Click the InfoPath 2007 Form Reader tab.
    The Input File sub-tab is in front.

  3. Select the Network file option.

  4. Click in the text box and enter the UNC path to the file, or click the Browse button and navigate through your network to find the InfoPath file you want to read.

    Note:
    You should select the .xml file that stores the completed form, not than the uncompleted InfoPath template.

  5. Click the Data Item Mapping tab and select the InfoPath template.

  6. Map the InfoPath form fields to Data Items through one of the following methods:

    • Mapping InfoPath Form Fields to Data Items

    • Automatically Mapping InfoPath Form Fields to Data Items

    • Copying Data Item Mappings from a Previous InfoPath Activity

  7. Click OK.
    The Properties window closes.

Related Topics

About the InfoPath 2007 Form Reader Activity | Reading from an InfoPath 2007 Document in the Template Directory | Reading from an InfoPath 2007 Document in a FilePointer Data Item | Reading from an InfoPath 2007 Document Stored in a SharePoint Repository


Reading from an InfoPath Form in a SharePoint Repository

You can use the InfoPath 2007 Form Reader activity to read text and other information from an InfoPath file stored in a SharePoint repository.

Important:
You can enter the address to any file on a SharePoint repository; however, you must have sufficient credentials in order to open the file when the activity runs. When you select your SharePoint site credentials, ensure they have the necessary privileges.

To Read Information from an InfoPath Document in a SharePoint Repository

  1. Add the InfoPath 2007 Form Reader activity to the Canvas and complete the common activity properties.

  2. Click the InfoPath 2007 Form Reader tab.
    The Input File sub-tab is in front.

  3. Select the SharePoint file option.

    • If the entire address to the SharePoint file will be stored in a Data Item, then choose the Select Data Item option.

    • If the address to the SharePoint file will be compiled from multiple Data Items, or if you know the entire address now, then choose the Enter File Path option.

      1. Click the Edit button to open a window that allows you to configure the SharePoint URL.

      2. Click in the URL box to enter the SharePoint URL.

      3. Optionally, click the Data Items drop-down list to select a Data Item that contains part of the SharePoint address, then click the Insert Display Value or Insert Value button to add the Data Item to the URL.

      4. Optionally, click the Preview URL button to see what the URL will look like when the Data Items are replaced with actual values.

      5. Click OK when you are done writing the SharePoint URL.

    Note:
    You should select the     .xml file that stores the completed form, not than the uncompleted InfoPath template.

  4. Select the method by which you wish to specify the SharePoint Server credentials.

    • To use the BPM engine credentials, choose the Use BPM Engine Credentials option, or

    • To manually enter credentials, choose the Enter Credentials option.

      1. Click the Engine Credentials button.

      2. Under the SharePoint username group box:

        • Choose Select Data Item, click the drop-down list, and select the Data Item that will contain the SharePoint username when the process runs, or

        • Choose Enter value and enter the SharePoint username now

      3. Under the SharePoint password group box:

        • Choose Select Data Item, click the drop-down list, and select the Data Item that will contain the SharePoint password when the process runs, or

        • Choose Enter value and enter the SharePoint password now

      4. If your SharePoint site is within a domain, then select the SharePoint Domain check box:

        • Choose Select Data Item, click the drop-down list, and select the Data Item that will contain the SharePoint domain name when the process runs, or

        • Choose Enter value and enter the SharePoint domain name now

      5. Click OK.

  5. Click the Data Item Mapping tab and select the InfoPath template.

  6. Map the InfoPath form fields to Data Items through one of the following methods:

    • Mapping InfoPath Form Fields to Data Items

    • Automatically Mapping InfoPath Form Fields to Data Items

    • Copying Data Item Mappings from a Previous InfoPath Activity

  7. Click OK.
    The Properties window closes.

Related Topics

About the InfoPath 2007 Form Reader Activity | Reading from an InfoPath 2007 Document in the Template Directory | Reading from an InfoPath 2007 Document in a Network Location | Reading from an InfoPath 2007 Document in a FilePointer Data Item


Reading from an InfoPath Form in the Template Directory

You can use the InfoPath 2007 Form Reader activity to read text and other information from an InfoPath document stored in the BPM Suite Template directory.

Important:
In order to read from an InfoPath document in the Template Directory, you must copy the InfoPath file to that directory on the process server. By default, the Template Directory is located on the BPM Server in C:\Program Files\Bluespring\repository\workflow\template\.

After adding an InfoPath file to the Template Directory, you need to add the name of the file to the Sys_InfoPathTemplates list.

To read information from an InfoPath document in the Template Directory

  1. Add the InfoPath 2007 Form Reader activity to the Canvas and complete the common activity properties.

  2. Click the InfoPath 2007 Form Reader tab.
    The Input File sub-tab is in front.

  3. Select the BPM Suite template option.

  4. Click the drop-down list and select the template from which you want to read.

    Note:
    The list of templates is based on the Sys_InfoPathTemplates list. If you have added a file to the template directory on the server, you also need to add it to the Sys_InfoPathTemplates list.

    Note:
    You should select the .xml file that stores the completed form, not than the uncompleted InfoPath template.

  5. Click the Data Item Mapping tab and select the InfoPath template.

  6. Map the InfoPath form fields to Data Items through one of the following methods:

    • Mapping InfoPath Form Fields to Data Items

    • Automatically Mapping InfoPath Form Fields to Data Items

    • Copying Data Item Mappings from a Previous InfoPath Activity

  7. Click OK.
    The Properties window closes.

Related Topics

About the InfoPath 2007 Form Reader Activity | Reading from an InfoPath 2007 Document in a Network Location | Reading from an InfoPath 2007 Document in a FilePointer Data Item | Reading from an InfoPath 2007 Document in a SharePoint Repository


Selecting the InfoPath Template File

Before you can map InfoPath form fields to Data Items, you need to select the InfoPath template (.xsn) that was used to create the InfoPath data file (.xml). The InfoPath 2007 Form Reader activity uses the template file to know which fields can be mapped to Data Items.

To Select an InfoPath Template File

  1. If you have not already done so, configure the activity to read from an InfoPath document in one of the following locations:

    • Reading from an InfoPath 2007 Form in the Template Directory

    • Reading from an InfoPath 2007 Form in a Network Location

    • Reading from an InfoPath 2007 Form in a FilePointer Data Item

    • Reading from an InfoPath 2007 Form in a SharePoint Repository

  2. Click the Data Item Mapping tab.

  3. Click the Browse button in the Template file section.

  4. Navigate to the location of the InfoPath template (.xsn file extension) and click Open.

    The     Form fields list becomes populated with every field in the template that the activity can read.

  5. Map the form fields to Data Items through one of the following methods:

    • Map InfoPath Form Fields to Data Items

    • Automatically Mapping InfoPath Form Fields to Data Items

    • Copy Data Item Mappings from a Previous InfoPath Activity

  6. Click OK.
    The Properties window closes.

Related Topics

About the InfoPath 2007 Form Reader Activity | Mapping InfoPath Form Fields to Data Items | Copying Data Item Mappings from a Previous InfoPath Activity


About the InfoPath 2007 Form Writer Activity

The InfoPath 2007 Form Writer activity allows you to write information from Data Items to InfoPath 2007 form fields. In order to write to an InfoPath form, you need to have access to the form template (.xsn file extension). You will need to locate the InfoPath template in three locations and for three purposes in this activity.

First, you need to locate the InfoPath template so the activity can access the template when it runs (in the "File location" section of the Input File tab).

Second, you need to enter the permanent location of the InfoPath template as a URL (in the "Original template file" section of the Input File tab). This URL is used to help the output XML file identify the template to which it is related.

Third, you need to locate the InfoPath template in a location that is accessible to you now, while you configure the activity (in the "InfoPath template file" section of the Data Item Mapping tab).

The activity requires you to select these files separately because the file you use when the activity runs might not be available now, when you configure the activity, and neither of those two files is necessarily available to the output XML file when the process is complete.

The output file created by this activity is an XML file that InfoPath recognizes as a completed form.

Choosing an InfoPath Document to Write To

The InfoPath document you write to can be stored in any one of four possible locations.

  • Writing to an InfoPath Form in the Template Directory

  • Writing to an InfoPath Form in a Network Location

  • Writing to an InfoPath Form in a FilePointer Data Item

  • Writing to an InfoPath Form in a SharePoint Repository

Selecting the InfoPath Template File to Reference

The output XML file must be able to reference the template file on which it is based. In order to provide the location of that file, you need to provide the location of a copy of the template file that will not change after the activity runs.

  • Selecting the InfoPath Template File to Reference

Setting up Mappings between Form Fields and Data Items

You need to select the InfoPath template file and map Data Items to its form fields.

  • Selecting an InfoPath Template File

  • Mapping Individual Data Items to InfoPath Form Fields

  • Automatically Mapping Data items to InfoPath Form Fields

  • Copying Data Item Mappings from a Previous InfoPath Activity

Choosing the Location of the Output File

The InfoPath Writer outputs an XML file that InfoPath recognizes as a completed form.

  • Saving the InfoPath File to a Data Item

  • Saving the InfoPath File to a SharePoint Repository

  • Defining the InfoPath File Name

Required Auxiliary Topics

Before you begin configuring an InfoPath 2007 Form Writer activity, make sure to complete the following:

  • Create Data Items that will store the form information you want the activity to write


Automatically Mapping Data Items to InfoPath Form Fields

You can map Data Item values to InfoPath form fields in three ways. First, you can map individual Data Items to form fields. Second, you can automatically map Data Items to form fields all at once, as long as those Data Items have the same name as the form fields. Finally, you can copy Data Item mappings from a previous InfoPath activity.

This article describes the second method of mapping Data Items to InfoPath Form Fields. In order to use this method, you must create Data Items that have the same names as the InfoPath form fields. For example, if the InfoPath template has a form field named additionalInfo, you would need to create a Data Item with the name additionalInfo.

To Automatically Map Data Items to InfoPath Form Fields

  1. If you have not already done so, configure the activity to write to an InfoPath document in one of the following locations:

    • Writing to an InfoPath 2007 Form in the Template Directory

    • Writing to an InfoPath 2007 Form in a Network Location

    • Writing to an InfoPath 2007 Form in a FilePointer Data Item

    • Writing to an InfoPath 2007 Form in a SharePoint Repository

  2. Enter the URL to a copy of the template that will be permanently available.

  3. Click the Data Item Mapping tab.

  4. If you have not already done so, select the InfoPath template file.

  5. If you have not already done so, create Data Items with names that match the InfoPath form field names. See the text at the beginning of this article for an example.

  6. Click the Map All button.
    All form fields that match Data Items are automatically mapped and added to the Data mapping selections list. Blank fields that are allowed to be blank are ommited. Form fields that are mapped to Data Items are removed from the Form fields list.

  7. Optionally, click the Remove Selected or Remove All buttons to remove any data mappings you do not need.

  8. Click OK.
    The Properties window closes.

Related Topics

About the InfoPath 2007 Form Writer Activity | Mapping Individual Data Items to InfoPath Form Fields | Copying Data Item Mappings from a Previous InfoPath Activity


Copying Data Item Mappings from a Previous InfoPath Activity

You can map Data Items to InfoPath form fields in three ways. First, you can map individual Data Items to form fields. Second, you can automatically map Data Items to form fields all at once, as long as those Data Items have the same name as the form fields. Finally, you can copy Data Item mappings from a previous InfoPath activity.

This article describes the third method of mapping Data Item values to InfoPath Form Fields. In order to use this method, you must have already configured an InfoPath activity, including setting up the Data Item mappings.

To Copy Data Item Mappings from a Previous InfoPath Activity

  1. If you have not already done so, configure the activity to write to an InfoPath document in one of the following locations:

    • Writing to an InfoPath 2007 Form in the Template Directory

    • Writing to an InfoPath 2007 Form in a Network Location

    • Writing to an InfoPath 2007 Form in a FilePointer Data Item

    • Writing to an InfoPath 2007 Form in a SharePoint Repository

  2. Enter the URL to a copy of the template that will be permanently available.

  3. Click the Data Item Mapping tab.

  4. If you have not already done so, select the InfoPath template file.

  5. Click the Copy Data Item Mappings button.
    A list of previous InfoPath activities appears.

  6. Select the InfoPath activity whose mappings you want to copy and click OK.
    The     Data mapping selections list shows the mappings you copied from the previous activity.

  7. Optionally, click the Remove Selected or Remove All buttons to remove any data mappings you do not need.

  8. Click OK.
    The Properties window closes.

Related Topics

About the InfoPath 2007 Form Writer Activity | Mapping Individual Data Items to InfoPath Form Fields | Automatically Mapping Data Items to InfoPath Form Fields


Defining the InfoPath File Name

After you select a location to save an InfoPath file (to a Data Item or to SharePoint), you also need to define a name for the file. The InfoPath file name can be a simple text string or it can be composed of multiple Data Items and/or Non-Data Item values.

To Define the InfoPath File Name

  1. If you have not already done so, configure the activity to write to an InfoPath document in one of the following locations:

    • Writing to an InfoPath 2007 Form in the Template Directory

    • Writing to an InfoPath 2007 Form in a Network Location

    • Writing to an InfoPath 2007 Form in a FilePointer Data Item

    • Writing to an InfoPath 2007 Form in a SharePoint Repository

  2. Enter the URL to a copy of the template that will be permanently available.

  3. If you have not already done so, click the Data Item Mapping tab and select the InfoPath template file.

  4. If you have not already done so, map Data Items to the InfoPath form fields through one of the following methods:

    • Mapping Individual Data Items to InfoPath Form Fields

    • Automatically Mapping Data Items to InfoPath Form Fields

    • Copying Data Item Mappings from a Previous InfoPath Activity

  4. Click the Output File tab.

  5. If you have not already done so, configure the activity to save the InfoPath document to one of the following two locations:

    • Saving the InfoPath File to a Data Item

    • Saving the InfoPath File to a SharePoint Repository

  6. Click the Edit button next to the Output file name box.
    A window that lets you design the file name appears.

  7. If you want to enter static text as the InfoPath file name, then click the File name box and enter text.

  8. If you want to include Data Item values in the Excel file name, select a Data Item in the Available Data Items list and click Insert Display Value or Insert Value.

    Note:
    There may be a difference between the Value and the Display Value of a Data Item.

  9. If you want to include a non-Data Item value in the Excel file name, then select one of the options in the Available Non-Data Items list and click Add.

    The File name field shows the final file name with placeholders for all the variables.

  10. Optionally, click the Preview File Name button to enter values for the variables and see what the final file name might look like.

  11. Click OK when you're done creating the output file name.

  12. The file name appears in the Output file name field on the Output File tab.

  13. Select the option that corresponds to how you want to handle the Excel file if another file with the same name already exists:

    • Select Overwrite the file, if it exists if you want the InfoPath file to overwrite any other files with the same name in the same location.

    • Select Increment the file name, if it exists if you want to add an incrementally higher number to the InfoPath file name rather than overwrite files with the same name. An incrementally higher file name has a number appended to the end. For example, FileName.xml would become FileName_1.xml, and then FileName_2.xml.

  14. Click OK.
    The Properties window closes.


Mapping Individual Data Items to InfoPath Form Fields

You can map Data Items to InfoPath form fields in three ways. First, you can map individual Data Items to form fields. Second, you can automatically map Data Items to form fields all at once, as long as those Data Items have the same name as the form fields. Finally, you can copy Data Item mappings from a previous InfoPath activity.

This article describes the first method of mapping Data Items to InfoPath Form Fields.

To Map Individual Data Items to InfoPath Form Fields

  1. If you have not already done so, configure the activity to write to an InfoPath document in one of the following locations:

    • Writing to an InfoPath 2007 Form in the Template Directory

    • Writing to an InfoPath 2007 Form in a Network Location

    • Writing to an InfoPath 2007 Form in a FilePointer Data Item

    • Writing to an InfoPath 2007 Form in a SharePoint Repository

  2. Enter the URL to a copy of the template that will be permanently available.

  3. Click the Data Item Mapping tab.

  4. If you have not already done so, select the InfoPath template file.

  5. Select a Data Item in the Data Items list and select an InfoPath form field in the Form fields list.

  6. Select Value or Display Value beneath the Data Items list to identify whether you want to write the value or display value of the Data Item.

  7. Click the Map button.
    The Form field name is removed from the Form fields list and the mapping is added to the Data mapping selections list.

  8. Repeat steps 5-7 to map as many Data Items and form fields as necessary.

  9. Optionally, click the Remove Selected or Remove All buttons to remove any data mappings you do not need.

  10. Click OK.
    The Properties window closes.

Related Topics

About the InfoPath 2007 Form Writer Activity | Automatically Mapping Data Items to InfoPath Form Fields | Copying Data Item Mappings from a Previous InfoPath Activity


Saving the InfoPath File to a Data Item

You can use the InfoPath 2007 Form Writer activity to save an InfoPath file in two different ways. You can save an InfoPath file to a FilePointer Data Item or you can save it to a SharePoint repository. You might want to save an InfoPath file to a Data Item if you plan to manipulate it multiple times throughout a process, or if you do not use SharePoint. You might want to save the file to SharePoint if you want to make the file available to people outside the context of the process and so that SharePoint can maintain a repository of your files.

To save an InfoPath File to a Data Item

  1. If you have not already done so, configure the activity to write to an InfoPath document in one of the following locations:

    • Writing to an InfoPath 2007 Form in the Template Directory

    • Writing to an InfoPath 2007 Form in a Network Location

    • Writing to an InfoPath 2007 Form in a FilePointer Data Item

    • Writing to an InfoPath 2007 Form in a SharePoint Repository

  2. Enter the URL to a copy of the template that will be permanently available.

  3. If you have not already done so, click the Data Item Mapping tab and select the InfoPath template file.

  4. If you have not already done so, map Data Items to the InfoPath form fields through one of the following methods:

    • Mapping Individual Data Items to InfoPath Form Fields

    • Automatically Mapping Data Items to InfoPath Form Fields

    • Copying Data Item Mappings from a Previous InfoPath Activity

  4. Click the Output File tab.

  5. Select the Output file to a Data Item option.

  6. Click the Data Item to store output file drop-down list and select the FilePointer Data Item that you want to hold the InfoPath file after the activity creates it.

    Note:
    Only FilePointer Data Items appear in this list.

  7. Define a file name for the InfoPath file.

  8. Click OK.
    The Properties window closes.


  1. Click the Edit button to open a window that allows you to configure the SharePoint URL.

  2. Click in the URL box to enter the SharePoint URL.

  3. Optionally, click the Data Items drop-down list to select a Data Item that contains part of the SharePoint address, then click the Insert Display Value or Insert Value button to add the Data Item to the URL.

  4. Optionally, click the Preview URL button to see what the URL will look like when the Data Items are replaced with actual values.

  5. Click OK when you are done writing the SharePoint URL.

Saving the InfoPath File to a SharePoint Repository

You can use the InfoPath 2007 Form Writer activity to save an InfoPath file in two different ways. You can save an InfoPath file to a FilePointer Data Item or you can save it to a SharePoint repository. You might want to save an InfoPath file to a Data Item if you plan to manipulate it multiple times throughout a process, or if you do not use SharePoint. You might want to save the file to SharePoint if you want to make the file available to people outside the context of the process and so that SharePoint can maintain a repository of your files.

To save an InfoPath file to a SharePoint Repository

  1. If you have not already done so, configure the activity to write to an InfoPath document in one of the following locations:

    • Writing to an InfoPath 2007 Form in the Template Directory

    • Writing to an InfoPath 2007 Form in a Network Location

    • Writing to an InfoPath 2007 Form in a FilePointer Data Item

    • Writing to an InfoPath 2007 Form in a SharePoint Repository

  2. Enter the URL to a copy of the template that will be permanently available.

  3. If you have not already done so, click the Data Item Mapping tab and select the InfoPath template file.

  4. If you have not already done so, map Data Items to the InfoPath form fields through one of the following methods:

    • Mapping Individual Data Items to InfoPath Form Fields

    • Automatically Mapping Data Items to InfoPath Form Fields

    • Copying Data Item Mappings from a Previous InfoPath Activity

  5. Click the Output File tab.

  6. Select the Output file to SharePoint option.

    • If the entire address to the SharePoint file will be stored in a Data Item, then choose the Select Data Item option. Click the drop-down list and select the Data Item that will contain the address to the SharePoint location where you want to save the file.

    • If the address to the SharePoint file should be compiled from multiple Data Items, or if you know the entire address now, then choose the Enter file path option.

  7. If the location on SharePoint where you want to save the file might not already exist when the activity runs, you can select the Create directory if it does not exist option. If you select this option, the InfoPath 2007 Form Writer activity will create directories as necessary to save the file in the specified location.

    Note:
    If you do not select this option, and the activity attempts to save a file in a location that does not exist, then the activity will generate an error. The process will still continue.

  8. Click the Enter Credentials button.

  9. Under the SharePoint username group box:

    • Choose Select Data Item, click the drop-down list, and select the Data Item that will contain the SharePoint username when the process runs, or

    • Choose Enter value and enter the SharePoint username now

  10. Under the SharePoint password group box:

    • Choose Select Data Item, click the drop-down list, and select the Data Item that will contain the SharePoint password when the process runs, or

    • Choose Enter value and enter the SharePoint password now

  11. If your SharePoint site is within a domain, then select the SharePoint Domain check box:

    • Choose Select Data Item, click the drop-down list, and select the Data Item that will contain the SharePoint domain name when the process runs, or

    • Choose Enter value and enter the SharePoint domain name now

  12. Click OK.

  13. If you want to save the entire path to the file (including the file name) after it has been saved in SharePoint, you can select the Store the complete file path (including file name) in a Data Item option. After you select that option, the drop-down list will be enabled and you will be able to select the Data Item that you want to contain the complete file path.

  14. Define a file name for the Excel file.

  15. Click OK.
    The Properties window closes.


Selecting the InfoPath Template File

Selecting an InfoPath Template File

Before you can map Data Item values to InfoPath form fields, you need to select the InfoPath template (.xsn) that you want to use to create the InfoPath data file (.xml). The InfoPath 2007 Form Writer activity uses the template file to know which InfoPath fields are available to accept Data Item values.

To Select an InfoPath Template File

  1. If you have not already done so, configure the activity to write to an InfoPath document in one of the following locations:

    • Writing to an InfoPath 2007 Form in the Template Directory

    • Writing to an InfoPath 2007 Form in a Network Location

    • Writing to an InfoPath 2007 Form in a FilePointer Data Item

    • Writing to an InfoPath 2007 Form in a SharePoint Repository

  2. Enter the URL to a copy of the template that will be permanently available.

  3. Click the Data Item Mapping tab.

  4. Click the Browse button in the InfoPath template file section.

  5. Navigate to the location of the InfoPath template (.xsn file extension) and click Open.

    The     Form fields list becomes populated with every field in the template that can accept Data Item values.

  6. Map the Data Items to the InfoPath form fields through one of the following methods:

    • Mapping Individual Data Items to InfoPath Form Fields

    • Automatically Mapping Data Items to InfoPath Form Fields

    • Copying Data Item Mappings from a Previous InfoPath Activity

  7. Determine where the completed InfoPath file will be stored and what its file name will be.

    • Saving the InfoPath File to a Data Item

    • Saving the InfoPath File to a SharePoint Repository

    • Defining the InfoPath File Name

  8. Click OK.
    The Properties window closes.

Related Topics

About the InfoPath 2007 Form Writer Activity | Mapping Individual Data Items to InfoPath Form Fields | Automatically Mapping Data Items to InfoPath Form Fields | Copying Data Item Mappings from a Previous InfoPath Activity


  1. Click the Edit button.

  2. Click the URL box and begin entering the URL or UNC file path.

  3. As necessary, click the Data Items drop-down list select a Data Item that contains part or all of the file path.

  4. Click Insert Display Value or Insert Value to insert the Display Value or Value of the Data Item.

  5. Optionally, click Preview URL to enter potential values for the Data Items and see how the resulting file path would look.

  6. Click OK to close the Original template file window.

Selecting the InfoPath Template File to Reference

The XML file that this activity outputs needs to be able to reference a permanent copy of the template on which it is based. Without this reference, InfoPath does not know how to use the information stored in the XML file.

Although you already selected a copy of the InfoPath template to use as a source file for the InfoPath Writer, you might not be able to use that same file as the reference in the output XML. For example, if your input file is in a FilePointer Data Item, it might not be accessible to the XML output file after the process runs. So the InfoPath Writer requires you to identify a copy of the template that will be accessible to the output XML file after the process runs.

To Select a Template File to Reference

  1. If you have not already done so, configure the activity to write to an InfoPath document in one of the following locations:

    • Writing to an InfoPath 2007 Form in the Template Directory

    • Writing to an InfoPath 2007 Form in a Network Location

    • Writing to an InfoPath 2007 Form in a FilePointer Data Item

    • Writing to an InfoPath 2007 Form in a SharePoint Repository

  2. Place a copy of the InfoPath template in a shared folder or on the Web. You can place the template file in any location where it will be accessible to the output XML file after the process runs.

  3. Click the URL box and enter the URL or UNC file path to the copy of the InfoPath template you just created.

  4. Optionally, you can click the Edit button to create a file path that includes Data Item values.

  5. Click the Data Item Mapping tab and select the InfoPath template.

  6. Map the Data Items to the InfoPath form fields through one of the following methods:

    • Mapping Individual Data Items to InfoPath Form Fields

    • Automatically Mapping Data Items to InfoPath Form Fields

    • Copying Data Item Mappings from a Previous InfoPath Activity

  7. Determine where the completed InfoPath file will be stored and what its file name will be.

    • Saving the InfoPath File to a Data Item

    • Saving the InfoPath File to a SharePoint Repository

    • Defining the InfoPath File Name

  8. Click OK.
    The Properties window closes.

Related Topics

About the InfoPath 2007 Form Writer Activity


Writing to an InfoPath Form in a FilePointer Data Item

You can use the InfoPath 2007 Form Writer activity to write text and other information to an InfoPath document stored in a FilePointer Data Item.

Important:
A FilePointer Data Item is a special type of Data Item. You can read more about storing a file in a Data Item.

To Write Information to an InfoPath Document in a FilePointer Data Item

  1. Add the InfoPath 2007 Form Writer activity to the Canvas and complete the common activity properties.

  2. Click the InfoPath 2007 Form Writer tab.
    The Input File sub-tab is in front.

  3. Select the FilePointer Data Item option.

  4. Click the drop-down list and select the FilePointer Data Item that will contain the InfoPath template you want to write to.

    Note:
    This Data Item should contain the actual template file (.xsn file extension).

  5. Enter the URL to a copy of the template that will be permanently available.

  6. Click the Data Item Mapping tab and select a copy of the InfoPath template that is available to you now.

  7. Map the Data Items to the InfoPath form fields through one of the following methods:

    • Mapping Individual Data Items to InfoPath Form Fields

    • Automatically Mapping Data Items to InfoPath Form Fields

    • Copying Data Item Mappings from a Previous InfoPath Activity

  8. Determine where the completed InfoPath file will be stored and what its file name will be through the following steps:

    • Saving the InfoPath File to a Data Item

    • Saving the InfoPath File to a SharePoint Repository

    • Defining the InfoPath File Name

  9. Click OK.
    The Properties window closes.

Related Topics

About the InfoPath 2007 Form Writer Activity | Writing to an InfoPath 2007 Document in the Template Directory | Writing to an InfoPath 2007 Document in a Network Location | Writing to an InfoPath 2007 Document Stored in a SharePoint Repository


Writing to an InfoPath Form in a Network Location

You can use the InfoPath 2007 Form Writer activity to write text and other information to an InfoPath file stored in a network location.

Important:
The InfoPath 2007 Form Writer activity allows you to select any file accessible to you when you design the process; however, the file also needs to be accessible to the process server when the process runs. For the best results, you should enter the path to the file in UNC format (e.g. \\ComputerName\sharedfolder\filename.extension).

To write information to an InfoPath document in a Network Location

  1. Add the InfoPath 2007 Form Writer activity to the Canvas and complete the common activity properties.

  2. Click the InfoPath 2007 Form Writer tab.
    The Input File sub-tab is in front.

  3. Select the Network file option.

  4. Click in the box and enter the UNC path to the file, or click the Browse button and navigate through your network to find the InfoPath template to which you want to write.

    Note:
    This Data Item should contain the actual template file (.xsn file extension).

  5. Enter the URL to a copy of the template that will be permanently available.

  6. Click the Data Item Mapping tab and select the InfoPath template.

  7. Map Data Items to the InfoPath form fields through one of the following methods:

    • Mapping Individual Data Items to InfoPath Form Fields

    • Automatically Mapping Data Items to InfoPath Form Fields

    • Copying Data Item Mappings from a Previous InfoPath Activity

  8. Determine where the completed InfoPath file will be stored and what its file name will be through the following steps.

    • Saving the InfoPath File to a Data Item

    • Saving the InfoPath File to a SharePoint Repository

    • Defining the InfoPath File Name

  9. Click OK.
    The Properties window closes.

Related Topics

About the InfoPath 2007 Form Writer Activity | Writing to an InfoPath 2007 Document in the Template Directory | Writing to an InfoPath 2007 Document in a FilePointer Data Item | Writing to an InfoPath 2007 Document Stored in a SharePoint Repository


Writing to an InfoPath Form in a SharePoint Repository

You can use the InfoPath 2007 Form Writer activity to write text and other information to an InfoPath file stored in a SharePoint repository.

Important:
You can enter the address to any file on a SharePoint repository; however, you must have sufficient credentials in order to open the file when the activity runs. When you select your SharePoint site credentials, ensure they have the necessary privileges.

To write information to an InfoPath document in a SharePoint Repository

  1. Add the InfoPath 2007 Form Writer activity to the Canvas and complete the common activity properties.

  2. Click the InfoPath 2007 Form Writer tab.
    The Input File sub-tab is in front.

  3. Select the SharePoint file option.

    • If the entire address to the SharePoint file will be stored in a Data Item, then choose the Select Data Item option.

    • If the address to the SharePoint file will be compiled from multiple Data Items, or if you know the entire address now, then choose the Enter File Path option.

      1. Click the Edit button
        The Input File Path window will appear, allowing you to configure the SharePoint URL.

      2. Click in the URL box to enter the SharePoint URL.

      3. Optionally, click the Data Items drop-down list to select a Data Item that contains part of the SharePoint address, then click the Insert Display Value or Insert Value button to add the Data Item to the URL.

      4. Optionally, click the Preview URL button to see what the URL will look like when the Data Items are replaced with actual values.

      5. Click OK when you are finished writing the SharePoint URL.

    Note:
    You should select the actual template file (ending with the     .xsn file extension).

  4. Select the method by which you wish to specify the SharePoint Server credentials.

    • To use the BPM engine credentials, choose the Use BPM Engine Credentials option, or

    • To manually enter credentials, choose the Enter Credentials option.

      1. Click the Enter Credentials button.

      2. Under the SharePoint username group box:

        • Choose Select Data Item, click the drop-down list, and select the Data Item that will contain the SharePoint username when the process runs, or

        • Choose Enter value and enter the SharePoint username now

      3. Under the SharePoint password group box:

        • Choose Select Data Item, click the drop-down list, and select the Data Item that will contain the SharePoint password when the process runs, or

        • Choose Enter value and enter the SharePoint password now

      4. If your SharePoint site is within a domain, then select the SharePoint Domain check box:

        • Choose Select Data Item, click the drop-down list, and select the Data Item that will contain the SharePoint domain name when the process runs, or

        • Choose Enter value and enter the SharePoint domain name now

      5. Click OK.

  5. Enter the URL to a copy of the template that will be permanently available.

  6. Click the Data Item Mapping tab and select the InfoPath template.

  7. Map Data Items to the InfoPath form fields through one of the following methods:

    • Mapping Individual Data Items to InfoPath Form Fields

    • Automatically Mapping Data Items to InfoPath Form Fields

    • Copying Data Item Mappings from a Previous InfoPath Activity

  8. Determine where the completed InfoPath file will be stored and what its file name will be.

    • Saving the InfoPath File to a Data Item

    • Saving the InfoPath File to a SharePoint Repository

    • Defining the InfoPath File Name

  9. Click OK.
    The Properties window closes.

Related Topics

About the InfoPath 2007 Form Writer Activity | Writing to an InfoPath 2007 Document in the Template Directory | Writing to an InfoPath 2007 Document in a Network Location | Reading from an InfoPath 2007 Document in a FilePointer Data Item


Writing to an InfoPath Form in the Template Directory

Writing to an InfoPath file in the Template Directory

You can use the InfoPath 2007 Form Writer activity to write text and other information to an InfoPath document stored in the BPM Suite Template directory.

Important:
In order to write to an InfoPath document in the Template Directory, you must copy the InfoPath file to that directory on the process server. By default, the Template Directory is located on the BPM Server in C:\Program Files\Bluespring\repository\workflow\template\

After adding an InfoPath file to the Template Directory, you need to add the name of the file to the Sys_InfoPathTemplates list.

To read information from an InfoPath document in the Template Directory

  1. Add the InfoPath 2007 Form Writer activity to the Canvas and complete the common activity properties.

  2. Click the InfoPath 2007 Form Writer tab.
    The Input File sub-tab is in front.

  3. Select the BPM Suite template option.

  4. Click the drop-down list and select the template you want to use to create the output file.

    Note:
    The list of templates is based on the Sys_InfoPathTemplates list. If you have added a file to the template directory on the server, you also need to add it to the Sys_InfoPathTemplates list.

    Note:
    You should select the actual template file that ends with a .xsn file extension.

  5. Enter the URL to a copy of the template that will be permanently available.

  6. Click the Data Item Mapping tab and select the InfoPath template.

  7. Map Data Items to the InfoPath form fields through one of the following methods:

    • Mapping Individual Data Items to InfoPath Form Fields

    • Automatically Mapping Data Items to InfoPath Form Fields

    • Copying Data Item Mappings from a Previous InfoPath Activity

  8. Determine where the completed InfoPath file will be stored and what its file name will be.

    • Saving the InfoPath File to a Data Item

    • Saving the InfoPath File to a SharePoint Repository

    • Defining the InfoPath File Name

  9. Click OK.
    The Properties window closes.

Related Topics

About the InfoPath 2007 Form Writer Activity | Writing to an InfoPath 2007 Document in a Network Location | Writing to an InfoPath 2007 Document in a FilePointer Data Item | Writing to an InfoPath 2007 Document in a SharePoint Repository


About the PDF Form Reader Activity

You can use the PDF Form Reader activity to read values from form fields in a PDF document. The PDF Form Reader activity is able to read from documents that are password protected, and it is able to read the file properties of a PDF document. This activity can also export the field values it reads to an XML format that Acrobat recognizes.

Important Requirements

The PDF Form Reader activity can only read PDF documents that are compatible with version 1.4 of the PDF standard.

You may need to have Adobe Acrobat Pro installed on your computer in order to match the PDF form fields with the Data Items that should store their values. Many publicly available forms (e.g. those distributed by the IRS or other government agencies) use non-descriptive field names, so it could be difficult to match the PDF form fields to the appropriate Data Items. However, if you open the PDF form in Adobe Acrobat Pro, then you can see the field names in the context of the form and be sure of what each form field name represents.

Choosing a PDF Document to Read

The PDF document you read can be stored in any one of four possible locations.

  • Reading from a PDF Form in the Template Directory

  • Reading from a PDF Form in a Network Location

  • Reading from a PDF Form in a FilePointer Data Item

  • Reading from a PDF Form in a SharePoint Repository

Opening PDF Documents with Password Protection

PDF documents can have two kinds of password protection enabled. This activity can use the correct password to open documents with password protection.

  • Opening a PDF with a Document Open Password

  • Opening a PDF with a Permissions Password

Setting up Mappings between Form Fields and Data Items

You need to select the PDF template file and map its form fields to Data Items.

  • Selecting the PDF Template File

  • Mapping Individual PDF Form Fields to Data Items

  • Automatically Mapping PDF Form Fields to Data Items

  • Copying Data Item Mappings from a Previous PDF Activity

Reading the File Properties of a PDF Document

  • Reading the Properties of a PDF File

Exporting Form Field Values to XML

  • Exporting PDF Form Field Values to XML

Required Auxiliary Topics

Before you begin configuring an PDF Form Reader activity, make sure to complete the following:

  • Create Data Items that will store the form information the activity will read


Automatically Mapping PDF Form Fields to Data Items

You can map PDF form fields to Data Items in three ways. First, you can map individual form fields to individual Data Items. Second, you can automatically map form fields to Data Items all at once, as long as those Data Items have the same name as the form fields. Finally, you can copy Data Item mappings from a previous PDF activity.

This article describes the second method of mapping PDF Form Fields to Data Items. In order to use this method, you must create Data Items that have the same names as the PDF form fields. For example, if the PDF document has a form field named additionalInfo, you would need to create a Data item with the name additionalInfo.

Note

The fields in many PDF forms do not have descriptive names. You may need to open the PDF of Adobe Acrobat Pro in order to see the field names in their context within the form.

To Automatically Map PDF Form Fields to Data Items

  1. If you have not already done so, configure the activity to read from a PDF form in one of the following locations:

    • Reading from a PDF Form in the Template Directory

    • Reading from a PDF Form in a Network Location

    • Reading from a PDF Form in a FilePointer Data Item

    • Reading from a PDF Form in a SharePoint Repository

  2. If necessary, click the Security tab and enter either of the following types of passwords:

    • Opening a PDF with a Document Open Password

    • Opening a PDF with a Permissions Password

  3. Click the Reading Options tab.

  4. If you have not already done so, select the PDF template file.

  5. If you have not already done so, create Data Items with names that match the PDF form field names. See the text at the beginning of this article for an example.

  6. Click the Map All button.
    All form fields that match Data Items are automatically mapped and added to the Data mapping selections list. Mapped Data Items are removed from the Data Items list.

  7. Optionally, click the Remove Selected or Remove All buttons to remove any data mappings you do not need.

  8. Click OK
    The Properties window closes.


Copying Data Item Mappings from a Previous PDF Activity

You can map PDF form fields to Data Items in three ways. First, you can map individual form fields with individual Data Items. Second, you can automatically map form fields to Data Items all at once, as long as those Data Items have the same name as the form fields. Finally, you can copy Data Item mappings from a previous PDF activity.

This article describes the third method of mapping PDF Form Fields to Data Items. In order to use this method, you must have already configured an PDF activity, including setting up the Data Item mappings.

To Copy Data Item Mappings from a Previous PDF Activity

  1. If you have not already done so, configure the activity to read from a PDF form in one of the following locations:

    • Reading from a PDF Form in the Template Directory

    • Reading from a PDF Form in a Network Location

    • Reading from a PDF Form in a FilePointer Data Item

    • Reading from a PDF Form in a SharePoint Repository

  2. If necessary, click the Security tab and enter either of the following types of passwords:

    • Opening a PDF with a Document Open Password

    • Opening a PDF with a Permissions Password

  3. Click the Reading Options tab.

  4. If you have not already done so, select the PDF template file.

  5. Click the Copy Data Item Mappings button.
    A list of previous PDF activities appears.

  6. Select the PDF activity whose mappings you want to copy and click OK.
    The     Data mapping selections list shows the mappings you copied from the previous activity.

  7. Optionally, click the Remove Selected or Remove All buttons to remove any data mappings you do not need.

  8. Click OK
    The Properties window closes.


Exporting PDF Form Field Values to XML

The PDF Form Reader activity is able to export the form values it reads as an XML file. The XML file is in a format that Adobe Acrobat understand and is able to import. You might want to export the PDF form values as XML if you want to parse the XML and use the form values for some other purpose, or if you want to import the XML file into a blank copy of the PDF form. Also, exporting PDF form values to an XML file means you would only need one FilePointer Data Item to contain every form field value, rather than using individual Data Items to hold each form value.

Note
You can import this kind of XML data to the PDF Form Writer activity.

To Export the PDF Form Field Values to an XML File

  1. If you have not already done so, configure the activity to read from a PDF form in one of the following locations:

    • Reading from a PDF Form in the Template Directory

    • Reading from a PDF Form in a Network Location

    • Reading from a PDF Form in a FilePointer Data Item

    • Reading from a PDF Form in a SharePoint Repository

  2. If necessary, click the Security tab and enter either of the following types of passwords:

    • Opening a PDF with a Document Open Password

    • Opening a PDF with a Permissions Password

  3. If you have not already done so, select the PDF template file.

  4. If you have not already done so, map the PDF form fields to Data Items through one of the following methods:

    • Mapping Individual PDF Form Fields to Data Items

    • Automatically Mapping PDF Form Fields to Data Items

    • Copying Data Item Mappings from a Previous PDF Activity

  5. Optionally, click the File Properties tab and read PDF file properties to Data Items.

  6. Click the Export to XML tab.

  7. Select the Export form fields to XML option to enable that section.

  8. Click the Data Item to store export file drop-down list and select the FilePointer Data Item that you want to store the exported XML.

  9. Click the Edit button next to the Export file name box. A window that lets you design the file name appears.

  10. If you want to enter static text as the XML file name, then click the File name box and enter text.

  11. If you want to include Data Item values in the XML file name, then select a Data Item in the Available Data Items list and click Insert Display Value or Insert Value.

    Note:     There may be a difference between the Value and the Display Value of a Data Item.

  12. If you want to include a non-Data Item value in the XML file name, then select one of the options in the Available Non-Data Items list and click Add.

    The File name field shows the final file name with placeholders for all the variables.

  13. Optionally, click the Preview File Name button to enter values for the variables and see what the final file name might look like.

  14. Click OK when you're done creating the output file name.

  15. The file name appears in the Export file name field.

  16. Click OK.
    The Properties window closes.

Related Topics

About the PDF Form Reader Activity


Mapping Individual PDF Form Fields to Data Items

You can map PDF form fields to Data Items in three ways. First, you can map individual form fields with individual Data Items. Second, you can automatically map form fields to Data Items all at once, as long as those Data Items have the same name as the form fields. Finally, you can copy Data Item mappings from a previous InfoPath activity.

This article describes the first method of mapping PDF form fields to Data Items.

Note

The fields in many PDF forms do not have descriptive names. You may need to open the PDF of Adobe Acrobat Pro in order to see the field names in their context within the form.

To Map Individual PDF Form Fields to Data Items

  1. If you have not already done so, configure the activity to read from a PDF form in one of the following locations:

    • Reading from a PDF Form in the Template Directory

    • Reading from a PDF Form in a Network Location

    • Reading from a PDF Form in a FilePointer Data Item

    • Reading from a PDF Form in a SharePoint Repository

  2. If necessary, click the Security tab and enter either of the following types of passwords:

    • Opening a PDF with a Document Open Password

    • Opening a PDF with a Permissions Password

  3. Click the Reading Options tab.

  4. If you have not already done so, select the PDF template file.

  5. Select a PDF form field in the Form fields list and select a Data Item in the Data Items list.

  6. Click the Map button.
    The Data Item is removed from the Data Items list and the mapping is added to the Data mapping selections list.

  7. Repeat steps 4-5 to map as many form fields and Data Items as necessary.

  8. Optionally, click the Remove Selected or Remove All buttons to remove any data mappings you do not need.

  9. Click OK
    The Properties window closes.

Related Topics

About the PDF Form Reader Activity | Automatically mapping PDF Form Fields to Data Items | Copying Data Item Mappings from a Previous PDF Activity


Opening a PDF with a Document Open Password

PDF documents support two kinds of passwords: Document Open Passwords and Permissions passwords. Document Open Passwords require a password before someone can open a PDF file. Permissions passwords allow you to restrict someone's access to a PDF file unless he or she enters the Permissions password. Although both passwords could be set to the same value, PDF considers them separate passwords.

If a document has both a Document Open Password and a Permissions password, you can enter only the Permissions password to unlock both the Document Open Password and the Permissions password. If your PDF file has a Permissions article, please refer to the article about opening a PDF with a permissions password.

To Open a PDF with a Document Open Password

  1. If you have not already done so, configure the activity to read from a PDF form in one of the following locations:

    • Reading from a PDF Form in the Template Directory

    • Reading from a PDF Form in a Network Location

    • Reading from a PDF Form in a FilePointer Data Item

    • Reading from a PDF Form in a SharePoint Repository

  2. Click the Security tab.

  3. Select the Document Open password option to enable that section.

  4. Enter the Document Open Password through one of the following options:

    • Choose the Select Data Item option. Click the drop-down list and select the Data Item that will contain the Document Open Password.

    • Choose the Enter password option. Enter the Document Open Password in the box.

  5. If necessary, enter the Permissions password.

  6. Click the Reading Options tab and select the PDF template.

  7. Map the PDF form fields to Data Items through one of the following methods:

    • Mapping Individual PDF Form Fields to Data Items

    • Automatically Mapping PDF Form Fields to Data Items

    • Copying Data Item Mappings from a Previous PDF Activity

  8. Optionally, click the File Properties tab and read PDF file properties to Data Items.

  9. Optionally, click the Export to XML tab and export the PDF form field values to XML.

    Note
    You can import this kind of XML data to the PDF Form Writer activity.

  10. Click OK.
    The Properties window closes.


Opening a PDF with a Permissions Password

PDF documents support two kinds of passwords: Document Open Passwords and Permissions passwords. Document Open Passwords require a password before someone can open a PDF file. Permissions passwords allow you to restrict someone's access to a PDF file unless he or she enters the Permissions password. Although both passwords could be set to the same value, PDF considers them separate passwords.

If a document has both a Document Open Password and a Permissions password, you can enter only the Permissions password to unlock both the Document Open Password and the Permissions password.

To Open a PDF with a Permissions Password

  1. If you have not already done so, configure the activity to read from a PDF form in one of the following locations:

    • Reading from a PDF Form in the Template Directory

    • Reading from a PDF Form in a Network Location

    • Reading from a PDF Form in a FilePointer Data Item

    • Reading from a PDF Form in a SharePoint Repository

  2. Click the Security tab.

  3. Select the Permissions password required option to enable that section.

  4. Enter the Permissions password through one of the following options:

    • Choose the Select Data Item option. Click the drop-down list and select the Data Item that will contain the Permissions password.

    • Choose the Enter password option. Enter the Permissions password in the box.

  5. Click the Reading Options tab and select the PDF template.

  6. Map the PDF form fields to Data Items through one of the following methods:

    • Mapping Individual PDF Form Fields to Data Items

    • Automatically Mapping PDF Form Fields to Data Items

    • Copying Data Item Mappings from a Previous PDF Activity

  7. Optionally, click the File Properties tab and read PDF file properties to Data Items.

  8. Optionally, click the Export to XML tab and export the PDF form field values to XML.

    Note
    You can import this kind of XML data to the PDF Form Writer activity.

  9. Click OK.
    The Properties window closes.


Reading from a PDF Form in a FilePointer Data Item

You can use the PDF Form Reader activity to read text and other information from a PDF form stored in a FilePointer Data Item.

Important:
A FilePointer Data Item is a special type of Data Item. You can read more about storing a file in a Data Item.

To read information from a PDF document in a FilePointer Data Item

  1. Add the PDF Form Reader activity to the Canvas and complete the common activity properties.

  2. Click the PDF Form Reader tab.
    The Input File sub-tab is in front.

  3. Select the FilePointer Data Item option.

  4. Click the drop-down list and select the FilePointer Data Item that will contain the PDF file you want to read.

  5. If necessary, click the Security tab and enter either of the following types of passwords:

    • Opening a PDF with a Document Open Password

    • Opening a PDF with a Permissions Password

  6. Click the Reading Options tab and select the PDF template.

  7. Map the PDF form fields to Data Items through one of the following methods:

    • Mapping Individual PDF Form Fields to Data Items

    • Automatically Mapping PDF Form Fields to Data Items

    • Copying Data Item Mappings from a Previous PDF Activity

  8. Optionally, click the File Properties tab and read PDF file properties to Data Items.

  9. Optionally, click the Export to XML tab and export the PDF form field values to XML.

    Note
    You can import this kind of XML data to the PDF Form Writer activity.

  10. Click OK.
    The Properties window closes.

Related Topics

About the PDF Form Reader Activity | Reading from a PDF Form in the Template Directory | Reading from a PDF Form in a Network Location | Reading from a PDF Form Stored in a SharePoint Repository


Reading from a PDF Form in a Network Location

You can use the PDF Form Reader activity to read text and other information from a PDF file stored in a network location.

Important:
The PDF Form Reader activity allows you to select any file accessible to you when you design the process; however, the file also needs to be accessible to the process server when the process runs. For the best results, you should enter the path to the file in UNC format (e.g. \\ComputerName\sharedfolder\filename.extension).

To read information from a PDF document in a Network Location

  1. Add the PDF Form Reader activity to the Canvas and complete the common activity properties.

  2. Click the PDF Form Reader tab.
    The Input File sub-tab is in front.

  3. Select the Network file option.

  4. Click in the box and enter the UNC path to the file, or click the Browse button and navigate through your network to find the PDF file you want to read.

  5. If necessary, click the Security tab and enter either of the following types of passwords:

    • Opening a PDF with a Document Open Password

    • Opening a PDF with a Permissions Password

  6. Click the Reading Options tab and select the PDF template.

  7. Map the PDF form fields to Data Items through one of the following methods:

    • Mapping Individual PDF Form Fields to Data Items

    • Automatically Mapping PDF Form Fields to Data Items

    • Copying Data Item Mappings from a Previous PDF Activity

  8. Optionally, click the File Properties tab and read PDF file properties to Data Items.

  9. Optionally, click the Export to XML tab and export the PDF form field values to XML.

    Note
    You can import this kind of XML data to the PDF Form Writer activity.

  10. Click OK.
    The Properties window closes.

Related Topics

About the PDF Form Reader Activity | Reading from a PDF Form in the Template Directory | Reading from a PDF Form in a FilePointer Data Item | Reading from a PDF Form Stored in a SharePoint Repository


Reading from a PDF Form in a SharePoint Repository

You can use the PDF Form Reader activity to read text and other information from a PDF form stored in a SharePoint repository.

Important:
You can enter the address to any file on a SharePoint repository; however, you must have sufficient credentials in order to open the file when the activity runs. When you enter your SharePoint site credentials, ensure they have the necessary privileges.

To read information from a PDF document in a SharePoint Repository

  1. Add the PDF Form Reader activity to the Canvas and complete the common activity properties.

  2. Click the PDF Form Reader tab.
    The Input File sub-tab is in front.

  3. Select the SharePoint file option.

    • If the entire address to the SharePoint file will be stored in a Data Item, then choose the Select Data Item option.

    • If the address to the SharePoint file will be compiled from multiple Data Items, or if you know the entire address now, then choose the Enter File Path option.

      1. Click the Edit button to open a window that allows you to configure the SharePoint URL.

      2. Click in the URL box to enter the SharePoint URL.

      3. Optionally, click the Data Items drop-down list to select a Data Item that contains part of the SharePoint address, then click the Insert Display Value or Insert Value button to add the Data Item to the URL.

      4. Optionally, click the Preview URL button to see what the URL will look like when the Data Items are replaced with actual values.

      5. Click OK when you are done writing the SharePoint URL.

  4. Click the Enter Credentials button.

  5. Under the SharePoint username group box:

    • Choose Select Data Item, click the drop-down list, and select the Data Item that will contain the SharePoint username when the process runs, or

    • Choose Enter value and enter the SharePoint username now

  6. Under the SharePoint password group box:

    • Choose Select Data Item, click the drop-down list, and select the Data Item that will contain the SharePoint password when the process runs, or

    • Choose Enter value and enter the SharePoint password now

  7. If your SharePoint site is within a domain, then select the SharePoint Domain check box:

    • Choose Select Data Item, click the drop-down list, and select the Data Item that will contain the SharePoint domain name when the process runs, or

    • Choose Enter value and enter the SharePoint domain name now

  8. Click OK.

  9. If necessary, click the Security tab and enter either of the following types of passwords:

    • Opening a PDF with a Document Open Password

    • Opening a PDF with a Permissions Password

  10. Click the Reading Options tab and select the PDF template.

  11. Map the PDF form fields to Data Items through one of the following methods:

    • Mapping Individual PDF Form Fields to Data Items

    • Automatically Mapping PDF Form Fields to Data Items

    • Copying Data Item Mappings from a Previous PDF Activity

  12. Optionally, click the File Properties tab and read PDF file properties to Data Items.

  13. Optionally, click the Export to XML tab and export the PDF form field values to XML.

    Note
    You can import this kind of XML data to the PDF Form Writer activity.

  14. Click OK.
    The Properties window closes.

Related Topics

About the PDF Form Reader Activity | Reading from a PDF Form in the Template Directory | Reading from a PDF Form in a Network Location | Reading from a PDF Form in a FilePointer Data Item


Reading from a PDF Form in the Template Directory

You can use the PDF Form Reader activity to read text and other information from a PDF document stored in the BPM Suite Template directory.

Important:
In order to read from a PDF document in the Template Directory, you must copy the InfoPath file to that directory on the process server. By default, the Template Directory is located on the BPM Server in C:\Program Files\Bluespring\repository\workflow\template\.

After adding a PDF file to the Template Directory, you need to add the name of the file to the Sys_PDFTemplates list.

To read information from an InfoPath document in the Template Directory

  1. Add the PDF Form Reader activity to the Canvas and complete the common activity properties.

  2. Click the PDF Form Reader tab.
    The Input File sub-tab is in front.

  3. Select the BPM Suite template option.

  4. Click the drop-down list and select the template from which you want to read.

    Note
    The list of templates is based on the Sys_PDFTemplates list. If you have added a file to the template directory on the server, you also need to add it to the Sys_PDFTemplates list.

  5. If necessary, click the Security tab and enter either of the following types of passwords:

    • Opening a PDF with a Document Open Password

    • Opening a PDF with a Permissions Password

  6. Click the Reading Options tab and select the PDF template.

  7. Map the PDF form fields to Data Items through one of the following methods:

    • Mapping Individual PDF Form Fields to Data Items

    • Automatically Mapping PDF Form Fields to Data Items

    • Copying Data Item Mappings from a Previous PDF Activity

  8. Optionally, click the File Properties tab and read PDF file properties to Data Items.

  9. Optionally, click the Export to XML tab and export the PDF form field values to XML.

    Note
    You can import this kind of XML data to the PDF Form Writer activity.

  10. Click OK.
    The Properties window closes.

Related Topics

About the PDF Form Reader Activity | Reading from a PDF Form in a Network Location | Reading from a PDF Form in a FilePointer Data Item | Reading from a PDF Form in a SharePoint Repository


Reading the Properties of a PDF File

You can use the PDF Form Reader to read the properties of the PDF file into Data Items. The PDF Form Reader supports reading the follow file properties of PDF documents:

  • Author

  • Creation Date

  • Creator

  • Keywords

  • Modified Date

  • Number of Pages

  • Producer

  • Subject

  • Title

To Read the Properties of a PDF File

  1. If you have not already done so, configure the activity to read from a PDF form in one of the following locations:

    • Reading from a PDF Form in the Template Directory

    • Reading from a PDF Form in a Network Location

    • Reading from a PDF Form in a FilePointer Data Item

    • Reading from a PDF Form in a SharePoint Repository

  2. If necessary, click the Security tab and enter either of the following types of passwords:

    • Opening a PDF with a Document Open Password

    • Opening a PDF with a Permissions Password

  3. Click the File Properties tab.

  4. Click the Value field next to the file property you want to read and select the Data Item that you want to store the file property.

  5. Repeat step 4 to select Data Items to store all of the file properties that you want to read.

  6. Click OK.
    The Properties window closes.

Related Topics

About the PDF Form Reader Activity


Selecting the PDF Template File

Before you can map PDF form fields to Data Items, you need to select a locally-accessible copy of the PDF form. The PDF Form Reader activity uses the local copy to know which fields can be mapped to Data Items.

To Select a PDF Template File

  1. If you have not already done so, configure the activity to read from a PDF form in one of the following locations:

    • Reading from a PDF Form in the Template Directory

    • Reading from a PDF Form in a Network Location

    • Reading from a PDF Form in a FilePointer Data Item

    • Reading from a PDF Form in a SharePoint Repository

  2. If necessary, click the Security tab and enter either of the following types of passwords:

    • Opening a PDF with a Document Open Password

    • Opening a PDF with a Permissions Password

  3. Click the Reading Options tab.

  4. Click the Browse button in the Template file section.

  5. Navigate to the location of the PDF form and click Open.

    The     Form fields list becomes populated with every field in the template that the activity can read.

  6. Map the PDF form fields to Data Items through one of the following methods:

    • Mapping Individual PDF Form Fields to Data Items

    • Automatically Mapping PDF Form Fields to Data Items

    • Copying Data Item Mappings from a Previous PDF Activity

  7. Optionally, click the File Properties tab and read PDF file properties to Data Items.

  8. Optionally, click the Export to XML tab and export the PDF form field values to XML.

    Note
    You can import this kind of XML data to the PDF Form Writer activity.

  9. Click OK.
    The Properties window closes.

Related Topics

About the PDF Form Reader Activity | Mapping Individual PDF Form Fields to Data Items | Automatically Mapping PDF Form Fields to Data Items | Copying Data Item Mappings from a Previous PDF Activity


About the PDF Form Writer Activity

You can use the PDF Form Writer activity to write values to form fields in a PDF document. The PDF Form Writer activity is able to write to documents that are password protected, and it is able to write to file properties of a PDF document. This activity can also import form field values from an XML format that Acrobat recognizes.

This activity also allows you to disable or enable password protection on the PDF, including the ability to set permissions.

Important Requirements

The PDF Form Writer activity can only write to PDF documents that are compatible with version 1.4 of the PDF standard.

You may need to have Adobe Acrobat Pro installed on your computer in order to match the PDF form fields with the Data Items that will contain their values. Many publicly available forms (e.g. those distributed by the IRS or other government agencies) use non-descriptive field names, so it could be difficult to match the PDF form fields to the appropriate Data Items. However, if you open the PDF form in Adobe Acrobat Pro, then you can see the field names in the context of the form and be sure of what each form field name represents.

Choosing a PDF Document to Write To

The PDF document you write to can be stored in any one of four possible locations.

  • Writing to a PDF Form in the Template Directory

  • Writing to a PDF Form in a Network Location

  • Writing to a PDF Form in a FilePointer Data Item

  • Writing to a PDF Form in a SharePoint Repository

Opening PDF Documents with Password Protection

PDF documents can have two kinds of password protection enabled. This activity can use the correct password to open documents with password protection. It can also change the passwords or remove them.

  • Opening a PDF with a Document Open Password

  • Changing or Creating a Document Open Password

  • Opening a PDF with a Permissions Password

  • Changing or Creating a Permissions Password

  • Removing Password Protection After Writing

Importing Form Field Values from XML

  • Importing PDF Form Field Values from XML

Setting up Mappings between Data Items and Form Fields

You need to select the PDF template file and map its form fields to Data Items.

  • Selecting the PDF Template File

  • Mapping Individual Data Items to PDF Form Fields

  • Automatically Mapping Data Items to PDF Form Fields

  • Copying Data Item Mappings from a Previous PDF Activity

Writing to the File Properties of a PDF Document

  • Writing Data Items to the PDF File Properties

Saving the PDF Output

  • Saving the PDF Form to a Data Item

  • Saving the PDF Form to a SharePoint Repository

  • Defining the PDF File Name

Required Auxiliary Topics

Before you begin configuring a PDF Form Writer activity, make sure to complete the following:

  • Create Data Items that will store the form information the activity will write


Automatically Mapping Data Items to PDF Form Fields

You can map Data Item values to PDF form fields in three ways. First, you can map individual Data Items to form fields. Second, you can automatically map Data Items to form fields all at once, as long as those Data Items have the same name as the form fields. Finally, you can copy Data Item mappings from a previous PDF activity.

This article describes the second method of mapping Data Items to InfoPath Form Fields. In order to use this method, you must create Data Items that have the same names as the InfoPath form fields. For example, if the InfoPath template has a form field named additionalInfo, you would need to create a Data item with the name additionalInfo.

To Automatically Map Data Items to PDF Form Fields

  1. If you have not already done so, configure the activity to write to a PDF form in one of the following locations:

    • Writing to a PDF Form in the Template Directory

    • Writing to a PDF Form in a Network Location

    • Writing to a PDF Form in a FilePointer Data Item

    • Writing to a PDF Form in a SharePoint Repository

  2. If necessary, click the Security tab and enter either of the following types of passwords:

    • Opening a PDF with a Document Open Password

    • Opening a PDF with a Permissions Password

  3. Optionally, you can remove, change, or create password protection:

    • Removing Password Protection After Writing

    • Changing or Creating a Document Open Password

    • Changing or Creating a Permissions Password

  4. Optionally, you can import an XML file that contains PDF form data.

    Note
    You can export this kind of XML data from the PDF Form Reader activity.

  5. If you have not already done so, click the Writing Options tab and select the PDF template.

  6. If you have not already done so, create Data Items with names that match the InfoPath form field names. See the text at the beginning of this article for an example.

  7. Click the Map All button.
    All form fields that match Data Items are automatically mapped and added to the Data mapping selections list. Form fields that are mapped to Data Items are removed from the Form fields list.

  8. Optionally, click the Remove Selected or Remove All buttons to remove any data mappings you do not need.

  9. Click OK.
    The Properties window closes.


Changing or Creating a Document Open Password

A Document Open Password requires a person to enter a password in order to view a PDF. You can use the PDF Form Writer activity to apply a Document Open Password to the PDF that the activity creates, or you can change the existing password.

To Change or Create a Document Open Password

  1. If you have not already done so, configure the activity to write to a PDF form in one of the following locations:

    • Writing to a PDF Form in the Template Directory

    • Writing to a PDF Form in a Network Location

    • Writing to a PDF Form in a FilePointer Data Item

    • Writing to a PDF Form in a SharePoint Repository

  2. Click the Security tab.

  3. Select the Change the Document Open Password option.

  4. Click the Change Password button.

  5. Enter the Current Document Open Password through one of the following methods:

    • Choose the Select Data Item option. Click the drop-down list and select the Data Item that will contain the current Document Open Password.

    • Choose the Enter password option. Enter the current password.

    Note
    If you are creating a new Document Open Password, and there is no "original" password, you can select either option but leave the field blank.

  6. Enter the New Document Open Password through one of the following methods:

    • Choose the Select Data Item option. Click the drop-down list and select the Data Item that will contain the new Document Open Password.

    • Choose the Enter password option. Enter the new password.

  7. Click OK.

  8. Optionally, you can import an XML file that contains PDF form data.

    Note
    You can export this kind of XML data from the PDF Form Reader activity.

  9. Click the Writing Options tab and select the PDF template.

  10. Map the PDF form fields to Data Items through one of the following methods:

    • Mapping Individual PDF Form Fields to Data Items

    • Automatically Mapping PDF Form Fields to Data Items

    • Copying Data Item Mappings from a Previous PDF Activity

  11. Optionally, click the File Properties tab and write Data Item values to PDF file properties.

  12. Click the Output File tab and determine where the completed PDF document will be stored and what its file name will be.

    • Saving the PDF File to a Data Item

    • Saving the PDF File to a SharePoint Repository

    • Defining the PDF File Name

  13. Click OK.
    The Properties window closes.


Changing or Creating a Permissions Password

A Permissions password allows you to limit the ways a user can manipulate a PDF. Any user can still view the document, but they cannot perform any of the restricted actions without first entering the Permissions password. You can use the PDF Form Writer activity to apply a Permissions password to the PDF that the activity creates, or you can change the existing password.

To Change or Create a Permissions Password

  1. If you have not already done so, configure the activity to write to a PDF form in one of the following locations:

    • Writing to a PDF Form in the Template Directory

    • Writing to a PDF Form in a Network Location

    • Writing to a PDF Form in a FilePointer Data Item

    • Writing to a PDF Form in a SharePoint Repository

  2. Click the Security tab.

  3. Select the Change the Permissions password option.

  4. Click the Change Password button.

  5. Enter the Current Permissions password through one of the following methods:

    • Choose the Select Data Item option. Click the drop-down list and select the Data Item that will contain the current Permissions password.

    • Choose the Enter password option. Enter the current Permissions password.

    Note
    If you are creating a new Permissions password, and there is no "original" password, you can select either option but leave the field blank.

  6. Enter the New Permissions password through one of the following methods:

    • Choose the Select Data Item option. Click the drop-down list and select the Data Item that will contain the new Permissions password.

    • Choose the Enter password option. Enter the new Permissions password.

  7. If you want to restrict the user's permissions, select the Permissions option to enable that section.

  8. Select any of the options to restrict the user's ability to manipulate the PDF.

  9. Click OK.

  10. Optionally, you can import an XML file that contains PDF form data.

    Note
    You can export this kind of XML data from the PDF Form Reader activity.

  11. Click the Writing Options tab and select the PDF template.

  12. Map the PDF form fields to Data Items through one of the following methods:

    • Mapping Individual PDF Form Fields to Data Items

    • Automatically Mapping PDF Form Fields to Data Items

    • Copying Data Item Mappings from a Previous PDF Activity

  13. Optionally, click the File Properties tab and write Data Item values to PDF file properties.

  14. Click the Output File tab and determine where the completed PDF document will be stored and what its file name will be.

    • Saving the PDF File to a Data Item

    • Saving the PDF File to a SharePoint Repository

    • Defining the PDF File Name

  15. Click OK.
    The Properties window closes.


Copying Data Item Mappings from a Previous PDF Activity

You can map Data Items to PDF form fields in three ways. First, you can map individual Data Items to form fields. Second, you can automatically map Data Items to form fields all at once, as long as those Data Items have the same name as the form fields. Finally, you can copy Data Item mappings from a previous PDF activity.

This article describes the third method of mapping Data Item values to InfoPath Form Fields. In order to use this method, you must have already configured a PDF activity, including setting up the Data Item mappings.

To Copy Data Item Mappings from a Previous PDF Activity

  1. If you have not already done so, configure the activity to write to a PDF form in one of the following locations:

    • Writing to a PDF Form in the Template Directory

    • Writing to a PDF Form in a Network Location

    • Writing to a PDF Form in a FilePointer Data Item

    • Writing to a PDF Form in a SharePoint Repository

  2. If necessary, click the Security tab and enter either of the following types of passwords:

    • Opening a PDF with a Document Open Password

    • Opening a PDF with a Permissions Password

  3. Optionally, you can remove, change, or create password protection:

    • Removing Password Protection After Writing

    • Changing or Creating a Document Open Password

    • Changing or Creating a Permissions Password

  4. Optionally, you can import an XML file that contains PDF form data.

    Note
    You can export this kind of XML data from the PDF Form Reader activity.

  5. If you have not already done so, click the Writing Options tab and select the PDF template.

  6. Click the Copy Data Item Mappings button.
    A list of previous InfoPath activities appears.

  7. Select the InfoPath activity whose mappings you want to copy and click OK.
    The     Data mapping selections list shows the mappings you copied from the previous activity.

  8. Optionally, click the Remove Selected or Remove All buttons to remove any data mappings you do not need.

  9. Click OK.
    The Properties window closes.


Defining the PDF File Name

After you select where to save the PDF file (to a Data Item or to SharePoint), you also need to define a name for the file. The PDF file name can be a simple text string or it can be composed of multiple Data Items and/or Non-Data Item values.

To Define the PDF File Name

  1. If you have not already done so, configure the activity to write to a PDF form in one of the following locations:

    • Writing to a PDF Form in the Template Directory

    • Writing to a PDF Form in a Network Location

    • Writing to a PDF Form in a FilePointer Data Item

    • Writing to a PDF Form in a SharePoint Repository

  2. If necessary, click the Security tab and enter either of the following types of passwords:

    • Opening a PDF with a Document Open Password

    • Opening a PDF with a Permissions Password

  3. Optionally, you can remove, change, or create password protection:

    • Removing Password Protection After Writing

    • Changing or Creating a Document Open Password

    • Changing or Creating a Permissions Password

  4. Optionally, you can import an XML file that contains PDF form data.

    Note
    You can export this kind of XML data from the PDF Form Reader activity.

  5. Click the Writing Options tab and select the PDF template.

  6. If you have not already done so, map the PDF form fields to Data Items through one of the following methods:

    • Mapping Individual PDF Form Fields to Data Items

    • Automatically Mapping PDF Form Fields to Data Items

    • Copying Data Item Mappings from a Previous PDF Activity

  7. Optionally, click the File Properties tab and write Data Item values to PDF file properties.

  8. Click the Output File tab.

  9. Click the Edit button next to the Output file name box. A window that lets you design the file name appears.

  10. If you want to enter static text as the InfoPath file name, then click the File name box and enter text.

  11. If you want to include Data Item values in the Excel file name, then select a Data Item in the Available Data Items list and click Insert Display Value or Insert Value.

    Note:     There may be a difference between the Value and the Display Value of a Data Item.

  12. If you want to include a non-Data Item value in the Excel file name, then select one of the options in the Available Non-Data Items list and click Add.

    The File name field shows the final file name with placeholders for all the variables.

  13. Optionally, click the Preview File Name button to enter values for the variables and see what the final file name might look like.

  14. Click OK when you're done creating the output file name.

  15. The file name appears in the Output file name field on the Output File tab.

  16. Select the option that corresponds to how you want to handle the Excel file if another file with the same name already exists:

    • Select Overwrite the file, if it exists if you want the InfoPath file to overwrite any other files with the same name in the same location.

    • Select Increment the file name, if it exists if you want to add an incrementally higher number to the InfoPath file name rather than overwrite files with the same name. An incrementally higher file name has a number appended to the end. For example, FileName.xml would become FileName-1.xml, and then FileName-2.xml.

  17. Click OK.
    The Properties window closes.


Importing PDF Form Field Values from XML

The PDF Form Writer activity is able to import PDF form values from an XML file. The XML file must be in a format that Adobe Acrobat understands and is able to import. You might want to import the PDF form values from XML if you exported the XML file from a PDF Form Reader activity. Importing PDF form values from an XML file means you would only need one FilePointer Data Item to contain every form field value, rather than using individual Data Items to hold each form value.

Note
You can import this kind of XML data to the PDF Form Writer activity.

Important

If you import XML data and map Data Items to form fields, the mapping will override the imported data.

To Import PDF Form Field Values from an XML File

  1. If you have not already done so, configure the activity to write to a PDF form in one of the following locations:

    • Writing to a PDF Form in the Template Directory

    • Writing to a PDF Form in a Network Location

    • Writing to a PDF Form in a FilePointer Data Item

    • Writing to a PDF Form in a SharePoint Repository

  2. If necessary, click the Security tab and enter either of the following types of passwords:

    • Opening a PDF with a Document Open Password

    • Opening a PDF with a Permissions Password

  3. Optionally, you can remove, change, or create password protection:

    • Removing Password Protection After Writing

    • Changing or Creating a Document Open Password

    • Changing or Creating a Permissions Password

  4. Click the Import XML tab.

  5. Select the Import XML form data option to enable that section.

  6. Click the FilePointer Data Item drop-down list and select the Data Item that contains the XML file with PDF form data inside.

  7. Click the Writing Options tab and select the PDF template.

  8. Map the PDF form fields to Data Items through one of the following methods:

    • Mapping Individual PDF Form Fields to Data Items

    • Automatically Mapping PDF Form Fields to Data Items

    • Copying Data Item Mappings from a Previous PDF Activity

  9. Optionally, click the File Properties tab and write Data Item values to PDF file properties.

  10. Click the Output File tab and determine where the completed PDF document will be stored and what its file name will be.

    • Saving the PDF File to a Data Item

    • Saving the PDF File to a SharePoint Repository

    • Defining the PDF File Name

  11. Click OK.
    The Properties window closes.

Related Topics

About the PDF Form Writer Activity


Mapping Individual Data Items to PDF Form Fields

You can map Data Items to PDF form fields in three ways. First, you can map individual Data Items to form fields. Second, you can automatically map Data Items to form fields all at once, as long as those Data Items have the same name as the form fields. Finally, you can copy Data Item mappings from a previous PDF activity.

This article describes the first method of mapping Data Items to PDF Form Fields.

To Map Individual Data Items to InfoPath Form Fields

  1. If you have not already done so, configure the activity to write to a PDF form in one of the following locations:

    • Writing to a PDF Form in the Template Directory

    • Writing to a PDF Form in a Network Location

    • Writing to a PDF Form in a FilePointer Data Item

    • Writing to a PDF Form in a SharePoint Repository

  2. If necessary, click the Security tab and enter either of the following types of passwords:

    • Opening a PDF with a Document Open Password

    • Opening a PDF with a Permissions Password

  3. Optionally, you can remove, change, or create password protection:

    • Removing Password Protection After Writing

    • Changing or Creating a Document Open Password

    • Changing or Creating a Permissions Password

  4. Optionally, you can import an XML file that contains PDF form data.

    Note
    You can export this kind of XML data from the PDF Form Reader activity.

  5. If you have not already done so, click the Writing Options tab and select the PDF template.

  6. Select a Data Item in the Data Items list and select an PDF form field in the Form fields list.

  7. Select Value or Display Value beneath the Data Items list to identify whether you want to write the value or display value of the Data Item.

  8. Click the Map button.
    The Form field name is removed from the Form fields list and the mapping is added to the Data mapping selections list.

  9. Repeat steps 6-8 to map as many Data Items and form fields as necessary.

  10. Optionally, click the Remove Selected or Remove All buttons to remove any data mappings you do not need.

  11. Click OK
    The Properties window closes.

Related Topics

About the PDF Form Writer Activity | Automatically Mapping Data Items to PDF Form Fields | Copying Data Item Mappings from a Previous PDF Activity


Opening a PDF with a Document Open Password

PDF documents support two kinds of passwords: Document Open Passwords and Permissions passwords. Document Open Passwords require a password before someone can open a PDF file. Permissions passwords allow you to restrict someone's access to a PDF file unless he or she enters the Permissions password. Although both passwords could be set to the same value, PDF considers them separate passwords.

If a document has both a Document Open Password and a Permissions password, you can enter only the Permissions password to unlock both the Document Open Password and the Permissions password.

To Open a PDF with a Document Open Password

  1. If you have not already done so, configure the activity to write to a PDF form in one of the following locations:

    • Writing to a PDF Form in the Template Directory

    • Writing to a PDF Form in a Network Location

    • Writing to a PDF Form in a FilePointer Data Item

    • Writing to a PDF Form in a SharePoint Repository

  2. Click the Security tab.

  3. Select the Document Open Password option to enable that section.

  4. Enter the Document Open Password through one of the following options:

    • Choose the Select Data Item option. Click the drop-down list and select the Data Item that will contain the Document Open Password.

    • Choose the Enter password option. Enter the Document Open Password in the box.

  5. If necessary, enter the Permissions password.

  6. Optionally, you can remove, change, or create password protection:

    • Removing Password Protection After Writing

    • Changing or Creating a Document Open Password

    • Changing or Creating a Permissions Password

  7. Optionally, you can import an XML file that contains PDF form data.

    Note
    You can export this kind of XML data from the PDF Form Reader activity.

  8. Click the Writing Options tab and select the PDF template.

  9. Map the PDF form fields to Data Items through one of the following methods:

    • Mapping Individual PDF Form Fields to Data Items

    • Automatically Mapping PDF Form Fields to Data Items

    • Copying Data Item Mappings from a Previous PDF Activity

  10. Optionally, click the File Properties tab and write Data Item values to PDF file properties.

  11. Click the Output File tab and determine where the completed PDF document will be stored and what its file name will be.

    • Saving the PDF File to a Data Item

    • Saving the PDF File to a SharePoint Repository

    • Defining the PDF File Name

  12. Click OK.
    The Properties window closes.


Opening a PDF with a Permissions Password

PDF documents support two kinds of passwords: Document Open Passwords and Permissions passwords. Document Open Passwords require a password before someone can open a PDF file. Permissions passwords allow you to restrict someone's access to a PDF file unless he or she enters the Permissions password. Although both passwords could be set to the same value, PDF considers them separate passwords.

If a document has both a Document Open Password and a Permissions password, you can enter only the Permissions password to unlock both the Document Open Password and the Permissions password.

To Open a PDF with a Permissions Password

  1. If you have not already done so, configure the activity to write to a PDF form in one of the following locations:

    • Writing to a PDF Form in the Template Directory

    • Writing to a PDF Form in a Network Location

    • Writing to a PDF Form in a FilePointer Data Item

    • Writing to a PDF Form in a SharePoint Repository

  2. Click the Security tab.

  3. Select the Permissions password option to enable that section.

  4. Enter the Permissions password through one of the following options:

    • Choose the Select Data Item option. Click the drop-down list and select the Data Item that will contain the Permissions password.

    • Choose the Enter password option. Enter the Permissions password in the box.

  5. Optionally, you can remove, change, or create password protection:

    • Removing Password Protection After Writing

    • Changing or Creating a Document Open Password

    • Changing or Creating a Permissions Password

  6. Optionally, you can import an XML file that contains PDF form data.

    Note
    You can export this kind of XML data from the PDF Form Reader activity.

  7. Click the Writing Options tab and select the PDF template.

  8. Map the PDF form fields to Data Items through one of the following methods:

    • Mapping Individual PDF Form Fields to Data Items

    • Automatically Mapping PDF Form Fields to Data Items

    • Copying Data Item Mappings from a Previous PDF Activity

  9. Optionally, click the File Properties tab and write Data Item values to PDF file properties.

  10. Click the Output File tab and determine where the completed PDF document will be stored and what its file name will be.

    • Saving the PDF File to a Data Item

    • Saving the PDF File to a SharePoint Repository

    • Defining the PDF File Name

  11. Click OK.
    The Properties window closes.


Removing Password Protection After Writing

If you open a PDF that has a Document Open Password and/or a Permissions password, and you provide the password(s) necessary to remove that protection, the PDF Form Writer activity can remove those passwords from the document. You might want to use this feature if you want a PDF file to remain protected before it is written to, but then remove the protection afterward.

After you perform the steps in this article, the output PDF will not have any password protection applied. If you only want to change the password protection (e.g. use a different password, change the specific permissions allowed), then refer to the articles on changing or creating a Document Open Password and changing or creating a Permissions password.

To Remove Password Protection After Writing

  1. If you have not already done so, configure the activity to write to a PDF form in one of the following locations:

    • Writing to a PDF Form in the Template Directory

    • Writing to a PDF Form in a Network Location

    • Writing to a PDF Form in a FilePointer Data Item

    • Writing to a PDF Form in a SharePoint Repository

  2. Click the Security tab.

  3. If a Document Open Password is applied to this PDF, enter the Document Open Password.

  4. If a Permissions password is applied to this PDF, enter the Permissions password.

  5. If you want to remove the Document Open Password, select the Remove the Document Open Password option in the After writing section.

  6. If you want to remove the Permissions password, select the Remove the Permissions password option in the After writing section.

  7. Optionally, you can import an XML file that contains PDF form data.

    Note
    You can export this kind of XML data from the PDF Form Reader activity.

  8. Click the Writing Options tab and select the PDF template.

  9. Map the PDF form fields to Data Items through one of the following methods:

    • Mapping Individual PDF Form Fields to Data Items

    • Automatically Mapping PDF Form Fields to Data Items

    • Copying Data Item Mappings from a Previous PDF Activity

  10. Optionally, click the File Properties tab and write Data Item values to PDF file properties.

  11. Click the Output File tab and determine where the completed PDF document will be stored and what its file name will be.

    • Saving the PDF File to a Data Item

    • Saving the PDF File to a SharePoint Repository

    • Defining the PDF File Name

  12. Click OK.
    The Properties window closes.


Saving the PDF Form to a Data Item

You can use the PDF Form Writer activity to save a PDF file in two different ways. You can save a PDF file to a FilePointer Data Item or you can save it to a SharePoint repository. You might want to save a PDF file to a Data Item if you plan to manipulate it multiple times throughout a process, or if you do not use SharePoint. You might want to save the file to SharePoint if you want to make the file available to people outside the context of the process and so that SharePoint can maintain a repository of your files.

To save a PDF file to a Data Item

  1. If you have not already done so, configure the activity to write to a PDF form in one of the following locations:

    • Writing to a PDF Form in the Template Directory

    • Writing to a PDF Form in a Network Location

    • Writing to a PDF Form in a FilePointer Data Item

    • Writing to a PDF Form in a SharePoint Repository

  2. If necessary, click the Security tab and enter either of the following types of passwords:

    • Opening a PDF with a Document Open Password

    • Opening a PDF with a Permissions Password

  3. Optionally, you can remove, change, or create password protection:

    • Removing Password Protection After Writing

    • Changing or Creating a Document Open Password

    • Changing or Creating a Permissions Password

  4. Optionally, you can import an XML file that contains PDF form data.

    Note
    You can export this kind of XML data from the PDF Form Reader activity.

  5. Click the Writing Options tab and select the PDF template.

  6. If you have not already done so, map the PDF form fields to Data Items through one of the following methods:

    • Mapping Individual PDF Form Fields to Data Items

    • Automatically Mapping PDF Form Fields to Data Items

    • Copying Data Item Mappings from a Previous PDF Activity

  7. Optionally, click the File Properties tab and write Data Item values to PDF file properties.

  8. Click the Output File tab.

  9. Select the Output file to a Data Item option.

  10. Click the Data Item to store output file drop-down list and select the FilePointer Data Item that you want to hold the PDF file after the activity creates it.

    Note:     Only FilePointer Data Items appear in this list.

  11. Define a file name for the PDF file.

  12. Click OK.
    The Properties window closes.


  1. Click the Edit button to open a window that allows you to configure the SharePoint URL.

  2. Click in the URL box to enter the SharePoint URL.

  3. Optionally, click the Data Items drop-down list to select a Data Item that contains part of the SharePoint address, then click the Insert Display Value or Insert Value button to add the Data Item to the URL.

  4. Optionally, click the Preview URL button to see what the URL will look like when the Data Items are replaced with actual values.

  5. Click OK when you are done writing the SharePoint URL.

Saving the PDF Form to a SharePoint Repository

You can use the PDF Form Writer activity to save a PDF file in two different ways. You can save a PDF file to a FilePointer Data Item or you can save it to a SharePoint repository. You might want to save a PDF file to a Data Item if you plan to manipulate it multiple times throughout a process, or if you do not use SharePoint. You might want to save the file to SharePoint if you want to make the file available to people outside the context of the process and so that SharePoint can maintain a repository of your files.

To save a PDF file to a SharePoint Repository

  1. If you have not already done so, configure the activity to write to a PDF form in one of the following locations:

    • Writing to a PDF Form in the Template Directory

    • Writing to a PDF Form in a Network Location

    • Writing to a PDF Form in a FilePointer Data Item

    • Writing to a PDF Form in a SharePoint Repository

  2. If necessary, click the Security tab and enter either of the following types of passwords:

    • Opening a PDF with a Document Open Password

    • Opening a PDF with a Permissions Password

  3. Optionally, you can remove, change, or create password protection:

    • Removing Password Protection After Writing

    • Changing or Creating a Document Open Password

    • Changing or Creating a Permissions Password

  4. Optionally, you can import an XML file that contains PDF form data.

    Note
    You can export this kind of XML data from the PDF Form Reader activity.

  5. Click the Writing Options tab and select the PDF template.

  6. If you have not already done so, map the PDF form fields to Data Items through one of the following methods:

    • Mapping Individual PDF Form Fields to Data Items

    • Automatically Mapping PDF Form Fields to Data Items

    • Copying Data Item Mappings from a Previous PDF Activity

  7. Optionally, click the File Properties tab and write Data Item values to PDF file properties.

  8. Click the Output File tab.

  9. Select the Output file to SharePoint option.

    • If the entire address to the SharePoint file will be stored in a Data Item, then choose the Select Data Item option. Click the drop-down list and select the Data Item that will contain the address to SharePoint location where you want to save the file.

    • If the address to the SharePoint file should be compiled from multiple Data Items, or if you know the entire address now, then choose the Enter file path option.

  10. If the location on SharePoint where you want to save the file might not already exist when the activity runs, you can select the Create directory if it does not exist option. If you select this option, the PDF Form Writer activity will create any directories as necessary to save the file in the specified location.

    Note:     If you do not select this option, and the activity attempts to save a file in a location that does not exist, then the activity will generate an error. The process will still continue.

  11. Click the Enter Credentials button.

  12. Under the SharePoint username group box:

    • Choose Select Data Item, click the drop-down list, and select the Data Item that will contain the SharePoint username when the process runs, or

    • Choose Enter value and enter the SharePoint username now

  13. Under the SharePoint password group box:

    • Choose Select Data Item, click the drop-down list, and select the Data Item that will contain the SharePoint password when the process runs, or

    • Choose Enter value and enter the SharePoint password now

  14. If your SharePoint site is within a domain, then select the SharePoint Domain check box:

    • Choose Select Data Item, click the drop-down list, and select the Data Item that will contain the SharePoint domain name when the process runs, or

    • Choose Enter value and enter the SharePoint domain name now

  15. Click OK.

  16. If you want to save the entire path to the file (including the file name) after it has been saved in SharePoint, you can select the Store the complete file path (including file name) in a Data Item option. After you select that option, the drop-down list will become enabled and you will be able to select the Data Item that you want to contain the complete file path.

  17. Define a file name for the PDF file.

  18. Click OK.
    The Properties window closes.


Selecting the PDF Template File

Before you can map Data Items to PDF form fields, you need to select a locally-accessible copy of the PDF form. The PDF Form Writer activity uses the local copy to know which fields can be mapped to Data Items.

To Select a PDF Template File

  1. If you have not already done so, configure the activity to write to a PDF form in one of the following locations:

    • Writing to a PDF Form in the Template Directory

    • Writing to a PDF Form in a Network Location

    • Writing to a PDF Form in a FilePointer Data Item

    • Writing to a PDF Form in a SharePoint Repository

  2. If necessary, click the Security tab and enter either of the following types of passwords:

    • Opening a PDF with a Document Open Password

    • Opening a PDF with a Permissions Password

  3. Optionally, you can remove, change, or create password protection:

    • Removing Password Protection After Writing

    • Changing or Creating a Document Open Password

    • Changing or Creating a Permissions Password

  4. Optionally, you can import an XML file that contains PDF form data.

    Note
    You can export this kind of XML data from the PDF Form Reader activity.

  5. Click the Writing Options tab.

  6. Click the Browse button in the PDF template file section.

  7. Navigate to the location of the PDF form and click Open.

    The     Form fields list becomes populated with every field in the PDF that the activity can write to.

  8. Map Data Items to the PDF form fields through one of the following methods:

    • Mapping Individual Data Items to PDF Form Fields

    • Automatically Mapping Data Items to PDF Form Fields

    • Copying Data Item Mappings from a Previous PDF Activity

  9. Optionally, click the File Properties tab and write Data Item values to PDF file properties.

  10. Click the Output File tab and determine where the completed PDF document will be stored and what its file name will be.

    • Saving the PDF File to a Data Item

    • Saving the PDF File to a SharePoint Repository

    • Defining the PDF File Name

  11. Click OK.
    The Properties window closes.

Related Topics

About the PDF Form Writer Activity | Mapping Individual Data Items to PDF Form Fields | Automatically Mapping Data Items to PDF Form Fields | Copying Data Item Mappings from a Previous PDF Activity


Writing Data Items to the PDF File Properties

You can use this option in the PDF Form Writer activity to add metadata information to the properties of the PDF file.

To Write Data Item values to the PDF Form Properties

  1. If you have not already done so, configure the activity to write to a PDF form in one of the following locations:

    • Writing to a PDF Form in the Template Directory

    • Writing to a PDF Form in a Network Location

    • Writing to a PDF Form in a FilePointer Data Item

    • Writing to a PDF Form in a SharePoint Repository

  2. If necessary, click the Security tab and enter either of the following types of passwords:

    • Opening a PDF with a Document Open Password

    • Opening a PDF with a Permissions Password

  3. Optionally, you can remove, change, or create password protection:

    • Removing Password Protection After Writing

    • Changing or Creating a Document Open Password

    • Changing or Creating a Permissions Password

  4. Optionally, you can import an XML file that contains PDF form data.

    Note
    You can export this kind of XML data from the PDF Form Reader activity.

  5. Click the Writing Options tab and select the PDF template.

  6. If you have not already done so, map the PDF form fields to Data Items through one of the following methods:

    • Mapping Individual PDF Form Fields to Data Items

    • Automatically Mapping PDF Form Fields to Data Items

    • Copying Data Item Mappings from a Previous PDF Activity

  7. Click the File Properties tab.

  8. Find the file property you want to set, located in the File Property column.

  9. Click the Source cell for that property and select .DisplayValue, .Value, or Constant.

    Select .DisplayValue if you want to use the Display Value of the Data Item.
    Select .Value if you want to use the Value of the Data Item.
    Select Constant if you want to enter the value for the file property now and use the same value every time the activity runs.

    Note:     Please refer to the help page titled Understanding the Difference Between Value and Display Value for more information on how to choose between those two values.

  10. Click the Value cell for that same property. If you selected .Display Value or .Value in the Source cell, then you can select the Data Item that will contain the value you want to write to that file property. However, if you selected Constant, then you can enter the value as text now.

  11. Click OK.
    The Properties window closes.

Related Topics

About the PDF Form Writer Activity


Writing to a PDF Form in a FilePointer Data item

You can use the PDF Form Writer activity to write text and other information to a PDF form stored in a FilePointer Data Item.

Important:
A FilePointer Data Item is a special type of Data Item. You can read more about storing a file in a Data Item.

To write information to a PDF document in a FilePointer Data Item

  1. Add the PDF Form Writer activity to the Canvas and complete the common activity properties.

  2. Click the PDF Form Writer tab.
    The Input File sub-tab is in front.

  3. Select the FilePointer Data Item option.

  4. Click the drop-down list and select the FilePointer Data Item that will contain the PDF file you want to write to.

  5. If necessary, click the Security tab and enter either of the following types of passwords:

    • Opening a PDF with a Document Open Password

    • Opening a PDF with a Permissions Password

  6. Optionally, you can remove, change, or create password protection:

    • Removing Password Protection After Writing

    • Changing or Creating a Document Open Password

    • Changing or Creating a Permissions Password

  7. Optionally, you can import an XML file that contains PDF form data.

    Note
    You can export this kind of XML data from the PDF Form Reader activity.

  8. Click the Writing Options tab and select the PDF template.

  9. Map the PDF form fields to Data Items through one of the following methods:

    • Mapping Individual PDF Form Fields to Data Items

    • Automatically Mapping PDF Form Fields to Data Items

    • Copying Data Item Mappings from a Previous PDF Activity

  10. Optionally, click the File Properties tab and write Data Item values to PDF file properties.

  11. Click the Output File tab and determine where the completed PDF document will be stored and what its file name will be.

    • Saving the PDF File to a Data Item

    • Saving the PDF File to a SharePoint Repository

    • Defining the PDF File Name

  12. Click OK.
    The Properties window closes.

Related Topics

About the PDF Form Writer Activity | Writing to a PDF Form in the Template Directory | Writing to a PDF Form in a Network Location | Writing to a PDF Form Stored in a SharePoint Repository


Writing to a PDF Form in a Network Location

You can use the PDF Form Writer activity to write text and other information to a PDF form stored in any accessible location within your network.

Important:
The PDF Form Writer activity allows you to select any file accessible to you when you design the process; however, the file also needs to be accessible to the process server when the process runs. For the best results, you should enter the path to the file in UNC format (e.g. \\ComputerName\sharedfolder\filename.extension).

To write information to a PDF document in a Network Location

  1. Add the PDF Form Writer activity to the Canvas and complete the common activity properties.

  2. Click the PDF Form Writer tab.
    The Input File sub-tab is in front.

  3. Select the Network file option.

  4. Click in the box and enter the UNC path to the file, or click the Browse button and navigate through your network to find the PDF file you want to write to.

  5. If necessary, click the Security tab and enter either of the following types of passwords:

    • Opening a PDF with a Document Open Password

    • Opening a PDF with a Permissions Password

  6. Optionally, you can remove, change, or create password protection:

    • Removing Password Protection After Writing

    • Changing or Creating a Document Open Password

    • Changing or Creating a Permissions Password

  7. Optionally, you can import an XML file that contains PDF form data.

    Note
    You can export this kind of XML data from the PDF Form Reader activity.

  8. Click the Writing Options tab and select the PDF template.

  9. Map the PDF form fields to Data Items through one of the following methods:

    • Mapping Individual PDF Form Fields to Data Items

    • Automatically Mapping PDF Form Fields to Data Items

    • Copying Data Item Mappings from a Previous PDF Activity

  10. Optionally, click the File Properties tab and write Data Item values to PDF file properties.

  11. Click the Output File tab and determine where the completed PDF document will be stored and what its file name will be.

    • Saving the PDF File to a Data Item

    • Saving the PDF File to a SharePoint Repository

    • Defining the PDF File Name

  12. Click OK.
    The Properties window closes.

Related Topics

About the PDF Form Writer Activity | Writing to a PDF Form in the Template Directory | Writing to a PDF Form in a FilePointer Data Item | Writing to a PDF Form Stored in a SharePoint Repository


Writing to a PDF Form in a SharePoint Repository

You can use the PDF Form Writer activity to write text and other information to a PDF form stored in a SharePoint repository.

Important:
You can enter the address to any file on a SharePoint repository; however, you must have sufficient credentials in order to open the file when the activity runs. When you enter your SharePoint site credentials, ensure they have the necessary privileges.

To write information to a PDF document in a SharePoint Repository

  1. Add the PDF Form Writer activity to the Canvas and complete the common activity properties.

  2. Click the PDF Form Writer tab.
    The Input File sub-tab is in front.

  3. Select the SharePoint file option.

    • If the entire address to the SharePoint file will be stored in a Data Item, then choose the Select Data Item option.

    • If the address to the SharePoint file will be compiled from multiple Data Items, or if you know the entire address now, then choose the Enter File Path option.

      1. Click the Edit button to open a window that allows you to configure the SharePoint URL.

      2. Click in the URL box to enter the SharePoint URL.

      3. Optionally, click the Data Items drop-down list to select a Data Item that contains part of the SharePoint address, then click the Insert Display Value or Insert Value button to add the Data Item to the URL.

      4. Optionally, click the Preview URL button to see what the URL will look like when the Data Items are replaced with actual values.

      5. Click OK when you are done writing the SharePoint URL.

  4. Click the Enter Credentials button.

  5. Under the SharePoint username group box:

    • Choose Select Data Item, click the drop-down list, and select the Data Item that will contain the SharePoint username when the process runs, or

    • Choose Enter value and enter the SharePoint username now

  6. Under the SharePoint password group box:

    • Choose Select Data Item, click the drop-down list, and select the Data Item that will contain the SharePoint password when the process runs, or

    • Choose Enter value and enter the SharePoint password now

  7. If your SharePoint site is within a domain, then select the SharePoint Domain check box:

    • Choose Select Data Item, click the drop-down list, and select the Data Item that will contain the SharePoint domain name when the process runs, or

    • Choose Enter value and enter the SharePoint domain name now

  8. Click OK.

  9. If necessary, click the Security tab and enter either of the following types of passwords:

    • Opening a PDF with a Document Open Password

    • Opening a PDF with a Permissions Password

  10. Optionally, you can remove, change, or create password protection:

    • Removing Password Protection After Writing

    • Changing or Creating a Document Open Password

    • Changing or Creating a Permissions Password

  11. Optionally, you can import an XML file that contains PDF form data.

    Note
    You can export this kind of XML data from the PDF Form Reader activity.

  12. Click the Writing Options tab and select the PDF template.

  13. Map the PDF form fields to Data Items through one of the following methods:

    • Mapping Individual PDF Form Fields to Data Items

    • Automatically Mapping PDF Form Fields to Data Items

    • Copying Data Item Mappings from a Previous PDF Activity

  14. Optionally, click the File Properties tab and write Data Item values to PDF file properties.

  15. Click the Output File tab and determine where the completed PDF document will be stored and what its file name will be.

    • Saving the PDF File to a Data Item

    • Saving the PDF File to a SharePoint Repository

    • Defining the PDF File Name

  16. Click OK.
    The Properties window closes.

Related Topics

About the PDF Form Writer Activity | Writing to a PDF Form in the Template Directory | Writing to a PDF Form Stored in a Network Location | Writing to a PDF Form in a FilePointer Data Item


Writing to a PDF Form in the Template Directory

You can use the PDF Form Writer activity to write text and other information to a PDF form stored in the BPM Suite Template directory.

Important:
In order to read from a PDF document in the Template Directory, you must copy the InfoPath file to that directory on the process server. By default, the Template Directory is located on the BPM Server in C:\Program Files\Bluespring\repository\workflow\template\.

After adding a PDF file to the Template Directory, you need to add the name of the file to the Sys_PDFTemplates list.

To write information to a PDF document in the Template Directory

  1. Add the PDF Form Writer activity to the Canvas and complete the common activity properties.

  2. Click the PDF Form Writer tab.
    The Input File sub-tab is in front.

  3. Select the BPM Suite template option.

  4. Click the drop-down list and select the template you want to write to.

    Note
    The list of templates is based on the Sys_PDFTemplates list. If you have added a file to the template directory on the server, you also need to add it to the Sys_PDFTemplates list.

  5. If necessary, click the Security tab and enter either of the following types of passwords:

    • Opening a PDF with a Document Open Password

    • Opening a PDF with a Permissions Password

  6. Optionally, you can remove, change, or create password protection:

    • Removing Password Protection After Writing

    • Changing or Creating a Document Open Password

    • Changing or Creating a Permissions Password

  7. Optionally, you can import an XML file that contains PDF form data.

    Note
    You can export this kind of XML data from the PDF Form Reader activity.

  8. Click the Writing Options tab and select the PDF template.

  9. Map the PDF form fields to Data Items through one of the following methods:

    • Mapping Individual PDF Form Fields to Data Items

    • Automatically Mapping PDF Form Fields to Data Items

    • Copying Data Item Mappings from a Previous PDF Activity

  10. Optionally, click the File Properties tab and write Data Item values to PDF file properties.

  11. Click the Output File tab and determine where the completed PDF document will be stored and what its file name will be.

    • Saving the PDF File to a Data Item

    • Saving the PDF File to a SharePoint Repository

    • Defining the PDF File Name

  12. Click OK.
    The Properties window closes.

Related Topics

About the PDF Form Writer Activity | Writing to a PDF Form Stored in a Network Location | Writing to a PDF Form in a FilePointer Data Item | Writing to a PDF Form in a SharePoint Repository


About the Text Writer Activity

You can use the Text Writer activity to write information from Data Items to a plain text (such as text, HTML, or XML) template and output the text to a Data Item or a SharePoint Web site. To begin, specify the template that will be used to create the text file. Data Item tokens in a template will be replaced at run time. The following table describes the syntax used for token replacement.

Token | Replacement Value
%Data Item.Value% | This token will be replaced by the Value of the Data Item
%Data Item.Display Value% | This token will be replaced by the Display Value of the Data Item
%foreach:<Data Item>% ... %end-foreach:<Data Item>% | Any text between the foreach and end-foreach tokens will be repeated for every instance of the specified Data Item

Choosing a template to write to

Click the links below to view the steps for writing values to templates.

  • Writing to a Template in the Template Directory

  • Writing to a Template in a Network Location

  • Writing to a Template in a FilePointer Data Item

  • Writing to a Template in a SharePoint Repository

  • Writing to a Template Defined in BPM Desinger

Next you need to determine where you will output the file. When you choose a location of the output file, you can change the file extension to anything you like.

Choosing the location of the output file

Click the links below to view the steps for determining where you would like to save the template.

  • Saving to a Data Item

  • Saving to a SharePoint Repository

  • Defining the Text File Name

Related Auxiliary Topics

Before you begin configuring a Text Writer activity, make sure to complete the following:

  • Create Data Items that will store the information the activity will write.


Adding the Template to Templates List

Adding the Template to the Templates List

Before you can read from or write to a text template, you must add the template to the Sys_TextTemplates list.

Important:
Make sure that the text template is stored in the BPM Suite repository folder, which by default is located on the BPM Server in C:\Program Files\Bluespring\repository\workflow\template\

To add a file to the Text Template Directory

  1. Open the List Management window.

  2. Double-click the Sys_TextTemplates list.
    The List Management (Sys_TextTemplates) window opens.

  3. Click the Value field in the empty row at the bottom of the list.

  4. Enter the name of the file exactly as it appears in the BPM Suite repository and press the Enter key.

    Example:
    Expense_Report_Read_Values.txt

  5. Click the Save List button.

  6. Close the list.
    The new list item you just created represents the actual text template file in the BPM Suite repository. You can select it from various drop-down lists to indicate the corresponding text file.


Defining the Text File Name

If you select to output to a file, you need to define a file name. The file name can be composed of multiple Data Items or non-Data Item values or both, or the text file name can be a simple text string.

To define the text file name

  1. Add the Text Writer activity to the Canvas and complete the common activity properties.

  2. Click the Text Writer tab.
    The Input Template subtab and Output File subtab appear.

  3. If you have not already done so, configure the activity to write to a template based in one of the following five locations:

    • Writing to a Template in the Template Directory

    • Writing to a Template in a Network Location

    • Writing to a Template in a FilePointer Data Item

    • Writing to a Template in a SharePoint Repository

    • Writing to a Template Defined in BPM Desinger

  4. Click the Output File subtab.

  5. If you have not already done so, configure the activity to save the text file to a Data Item.

    Note:
    If you select Output file to SharePoint, File Options is unavailable.

  6. Under File options, type the text file name in the Output file name box

    -or-

    click the Edit button to design the file name.

    If you click the Edit button, the Configure Output File Name window appears, allowing you to add Data Items and non-Data Item values to the file name.

    Tip:
    You must indicate the file extension. By default, no file extension is added.

  7. Select the option that corresponds with how you want to handle the text file if another file with the same name already exists:

    • Click Overwrite the file if it exists if you want the text file to overwrite any other files with the same name in the same location.

    • Click Increment the file name if it exists if you want to add an incrementally higher number to the text file name rather than overwrite files with the same name. An incrementally higher file name has a number appended to the end. For example, FileName.txt would become FileName-1.txt, and then FileName-2.txt.

  8. Click OK.
    The Properties for Activity window closes.


Editing the Output Name

  1. In the Configure Output File Name window, type the static file name in the File Name box

    -or-

    include a Data Item in the text file name by performing any of the following steps:

  2. Double-click a Data Item in the Available Data Items (the value appears in File name)

  3. Select a Data Item, and then click Insert Display Value or Insert Value

  4. Select a Data Item, and then click Add

To include a non-Data Item value in the text file name, select one of the options in the Available Non-Data Items list, and then click Add.

Note:
There may be a difference between the Value and the Display Value of a Data Item.

The File name field shows the final file name with placeholders for all the variables.

  2. Click the Preview File Name button.
    A screen displays test values to preview, allowing you to add variables in the right column.

  3. Click Preview File Name.
    Your complete file name is displayed in the File Name box.

  4. Click OK to close the Preview File Name window.

  5. Click OK to close the Configure Output File Name window.
    The file name appears in the Output file name field on the Output File tab


Entering Credentials

  1. Under SharePoint user name, click Select Data item

    -    or-

    click Enter value.

    If you click Select Data Item, click the down arrow, and select the Data Item that corresponds to your username.
    If you click Enter value, type the username you use to access your network.

  2. Under SharePoint password, click Select Data Item

    -or-

    click Enter value.

    If you click Select Data Item, click the down arrow, and select a Data Item that contains a SharePoint password.
    If you click Enter value, type the password used in association with the username in step 1.

    Note:
    These credentials will be stored in the activity configuration. Previously indicated credentials will be replaced.

  3. Select the SharePoint Domain check box.
    This field allows you to indicate the domain name of your network.

  4. Click Select Data Item

    - or-

    click Enter value.

    If you click Select Data Item, select the Data Item that contains the domain name of your network.
    If you click Enter value, type the domain name of your network.

  5. Click OK.
    The window closes and you return to the Properties for Activities window.


Saving the Text File to a Data Item

You can use the Text Writer activity to save a text file in two different ways. You can save a text file to a Data Item (FilePointer, Text, or HTML), or you can save the text file to a SharePoint repository. You might want to save to a Data Item if you plan to manipulate the file multiple times throughout a process or if you do not use SharePoint. You might want to save to a SharePoint site if you want to make the file available to people outside the context of the process and so SharePoint can maintain a repository of your files.

To save a text file to a Data Item

  1. Add the Text Writer activity to the Canvas and complete the common activity properties.

  2. Click the Text Writer tab.
    The Input File subtab and Output File subtab appear.

  3. If you have not already done so, configure the activity to write to an Excel document based in one of the following four locations:

  4. Writing to a Template in the Template Directory

  5. Writing to a Template in a Network Location

  6. Writing to a Template in a FilePointer Data Item

  7. Writing to a Template in a SharePoint Repository

  8. Writing to a Template Defined in BPM Desinger

  4. Click the Output File subtab.

  5. Select the Output to a Data Item option.

  6. Click Select FilePointer Data Item

    -or-

    click Select Text or HTML Data Item.

    If you click Select FilePointer Data Item, click the down arrow, and then click the FilePointer Data Item that you want to hold the text file after the activity writes to it.
    If you click Select Text or HTML Data Item, click the down arrow, and then click the Text or HTML Data Item that you want to hold the text file after the activity writes to it.

    Note:
    Outputting to a FilePointer Data Item will create a file, and outputting to a Text Data Item or an HTML Data Item will write the modified input file contents as the Data Item.

  7. If you have clicked Select FilePointer Data Item, define a file name for the text file.
    Clicking Select Text or HTML Data Item will disable the option of defining a file name.

  8. Click OK.
    The Properties for Activity window closes.

Related Topics

About the Text Writer Activity | Saving the Text File to a SharePoint Repository


Saving the Text File to a SharePoint Repository

You can use the Text Writer activity to save a text file in two different ways. You can save a text file to a FilePointer Data Item or you can save it to a SharePoint repository. You might want to save a text file to a Data Item if you plan to manipulate it multiple times throughout a process, or if you do not use SharePoint. Also, you might want to save the file to SharePoint if you want to make the file available to people outside the context of the process and so that SharePoint can maintain a repository of your files.

To save a text file to a SharePoint repository

  1. Add the Text Writer activity to the Canvas and complete the common activity properties.

  2. Click the Text Writer tab.
    The Input File subtab and Output File subtab appear.

  3. If you have not already done so, configure the activity to write to an text document based in one of the following four locations:

  4. Writing to a Template in the Template Directory

  5. Writing to a Template in a Network Location

  6. Writing to a Template in a FilePointer Data Item

  7. Writing to a Template in a SharePoint Repository

  8. Writing to a Template Defined in BPM Desinger

  4. Click the Output File subtab.

  5. Select the Output file to SharePoint option.

  6. If the entire address to the SharePoint file will be stored in a Data Item, click the Select Data Item option, click the drop-down arrow, and then click the Data Item that will contain the address to the SharePoint location where you want to save the file.

  7. If the address to the SharePoint file should be compiled from multiple Data Items, or if you know the entire address, then click the Enter file path option.

      1. Click the Edit button
        The Output Path Name window appears, allowing you to configure the SharePoint URL.

      2. Click in the URL box and enter the SharePoint URL

        -or-

        click the Data Items drop-down arrow to select a Data Item that contains part of the SharePoint address, then click the Insert Display Value or Insert Value button to add the Data Item to the URL.

        Clicking the Preview URL button allows you to see how the URL will look when the Data Items are replaced with actual values.

      3. Click OK to close the Preview File Name window.

      4. When you are done writing the SharePoint URL, click OK
        The Output Path Name window closes.

  6. Click the Use BPM Engine Credentials option

    -    or-

    click the Enter Credentials button.

    If you click Use BPM Engine Credentials, the rights and privileges of the server's username will direct your access.
    If you click Enter Credentials, complete the dialogue box to authenticate to the SharePoint site using the information you use to log on to your network.

  7. Click the Create directory if it does not exist option if the SharePoint location where you want to save the file does not exist when the activity runs.
    The Text Writer activity will create any directories as necessary to save the file in the specified location.

    Note:     If you do not select this option, and the activity attempts to save a file in a location that does not exist, the activity will generate an error. However, the process will still continue.

  8. Click the Store the complete file path (including file name) in a Data Item option if you want to save the entire path to the file after it has been saved in SharePoint, you can select. After you select that option, click the down arrow to select the Data Item that you want to contain the complete file path.

  9. Click OK.
    The Properties for Activity window closes.


Setting the Web Address

The Web Address Edit Button

  1. Select a Data Item from the Data Items drop-down list.
    In the URL box, the location of your pointer in the address will determine the placement of the selected Item.

  2. Click Insert Display Value

    - or-

    Click the Insert Value to insert the Data Item value.

    If you click Insert Display Value, the Data Item display value will be inserted into the SharePoint site address.
    If you click Insert Value, the Data Item value will be inserted into the Sharepoint site address.

    Note:
    The Data Item will appear beginning and ending with percent signs. Either .DisplayValue or .Value will be added to the XML Tag of the selected Data Item. You can manually enter Data Items if you know the correct syntax, which is %DataItem.DisplayValue% or %DataItem.Value%.

  3. Click Preview URL.
    A screen displays test values to preview, allowing you to add a URL in the right column.

  4. Click Preview URL.
    Your address displays in the URL field.

  5. Click OK.
    You will return to Properties for Activities when you click OK once more.

  6. Click OK.


Writing to a Template Defined in BPM Designer

You can edit an existing template by adding Data Items values. You must first choose a template that will be used to create the text file in order to begin this procedure.

To write Data Item values, display values, and repeat values to an existing template

  1. Add the Text Writer activity to the Canvas and complete the common activity properties.

  2. Click the Text Writer tab.
    The Input Template subtab and Output File subtab appear.

  3. Under the Input Template subtab, click Define the template.

  4. Click the Edit Template button.
    The Edit Template window appears with text of the previously defined input template in the bottom pane. All available Data Items in your project appear in the top pane.

  5. Insert the display value or the value of Data Items into the text of the template, or have Data Item values repeat. You can do this two ways.

  6. Click the Insert Display Value option, the Insert Value option, or the Insert Repeating Section option, and then drag the desired Data Item to the bottom pane. Either the display value, the value of the Data Item, or the repeating indicators you dragged will appear in the lower pane. The text enclosed in the third option will repeat for each instance of the specified Data Item.

  7. Click the Data Item to select it, and then click the Insert Value button, the Insert Display Value button, or the Insert Repeating Section button. The value will insert in the text according to the most recent placement of your pointer.

    Note:
    The button overrides whatever option that may be chosen. For example, although the Use Value option may be selected, the Display Value will insert in the text when you click the Insert Display Value button.

  6. Click OK.
    The Edit Template window closes, and you return to the Input File subtab.

    Note:
    If you exit the Properties for Activity window before all required information is entered, a message appears to let you know what information is needed to compete the process.

  7. Click the Output File subtab.

  8. Determine where to store the completed text document and what the file name will be.

  9. Saving the Text File to a Data Item

  10. Saving the Text File to a SharePoint Repository

  11. Defining the Text File Name

  9. Click OK.
    The Properties for Activity window closes.

Related Topics

About the Text Writer Activity | Writing to a Text File in the Template Directory | Writing to a Text File in a Network Location | Writing to a Text File in a SharePoint Repository


Writing to a Template in a FilePointer Data Item

You can use the Text Writer activity to write Data Item values to a plain text template stored in a FilePointer Data Item. For more information on FilePointer Data Items, refer to the article titled Storing a File in a Data Item.

To write Data Item values to a template in a FilePointer Data Item

  1. Add the Text Writer activity to the Canvas and complete the common activity properties.

  2. Click the Text Writer tab.
    The Input File subtab and Output File subtab appear.

  3. Under the Input File subtab, click the Load the template from a file option.

  4. Click the FilePointer Data Item option.

  5. Click the FilePointer Data Item drop-down arrow, and then click the FilePointer Data Item that contains the text file that you want to modify.

    Note:
    Only FilePointer Data Items appear in this list.

  6. Click the Output File subtab.

  7. Determine where to store the completed text document and what its file name will be.

  8. Saving the Text File to a Data Item

  9. Saving the Text File to a SharePoint Repository

  10. Defining the Text File Name

  8. Click OK.
    The Properties for Activity window closes.

Related Topics

About the Text Writer Activity | Writing to a Text File in the Template Directory | Writing to a Text File in a Network Location | Writing to a Text File in a SharePoint Repository


The following address is the UNC format:

\computername\shareholder\resource. In most situations, the computer you use to design the process is not the same as the server that executes the process. In this case, a local path (such as one that begins with C:\) will point to a different location on different computers.

Writing to a Template in a Network Location

You can use the Text Writer activity to write Data Item values to a plain text template stored in any accessible location on your network. The file you select must be accessible to the server that hosts BPM Server when the process runs.

Hint:
It is probably easiest to find a file within your network if that file is in a shared directory. Contact your system administrator if you need help setting up a shared directory in Windows.

To write Data Item values to a template in a network location

  1. Add the Text Writer activity to the Canvas and complete the common activity properties.

  2. Click the Text File Writer tab.
    The Input File subtab and Output File subtab appear.

  3. Under the Input File subtab, click the Load the template from a file option.

  4. Select the Network file option.

  5. Enter the location of the file you want to write to in one of two ways.

  6. Type the file path in the text box.

  7. Click Browse to view a graphical representation of all of the computers on your network. Select a location, and then click OK.

    Note:
    If you enter the path to the file manually, then you should enter that path in Universal Naming Convention (UNC) format. UNC is a common syntax for describing the location of files and folders on a network.

  6. Click the Output File subtab.

  7. Determine where to store the completed text.

  8. Saving the Text File to a Data Item

  9. Saving the Text File to a SharePoint Repository

  10. Defining the Text File Name

  8. Click OK.
    The Properties for Activity window closes.

Related Topics

About the Text Writer Activity | Writing to a Text File in the Template Directory | Writing to a Text File in a FilePointer Data Item | Writing to a Text File in a SharePoint Repository


Writing to a Template in a SharePoint Repository

You can use the Text Writer activity to write Data Item values to a plain text template stored in a SharePoint Repository.

Important:

You can enter the address to any file in a SharePoint repository; however, you must have sufficient credentials in order to open the file when the process runs. Make sure you have the necessary privileges when you select your SharePoint site credentials.

To write Data Item values to a template in a SharePoint repository

  1. Add the Text Writer activity to the Canvas and complete the common activity properties.

  2. Click the Text Writer tab.
    The Input File subtab and Output File subtab appear.

  3. Under the Input File subtab, click the SharePoint file option.

  4. Click Select Data Item if the SharePoint file will be stored in one Data Item

    -or-

    click Enter file path if the address to the SharePoint file will be compiled from multiple Data Items or if you know the address.

    If you click Select Data Item, click the drop-down list, and then click the Data Item that will contain the address to the file on SharePoint.
    If you click Enter file path, type the SharePoint address. As an option, you can click the Edit button to include Data Item values with the address you typed.

  5. Click the Use BPM Engine Credentials option

    -or-

    click the Enter Credentials button.

    If you click Use BPM Engine Credentials, the rights and privileges of the server's username will direct your access.
    If you click Enter Credentials, complete the dialogue box to authenticate to the SharePoint site using the information you use to log on to your network.

  6. Click the Output File subtab.

  7. Determine where to store the completed text.

  8. Saving the Text File to a Data Item

  9. Saving the Text File to a SharePoint Repository

  10. Defining the Text File Name

  8. Click OK.
    The Properties for Activity window closes.

Related Topics

About the Text Writer Activity | Writing to a Text File in the Template Directory | Writing to a Text File in a Network Location | Writing to a Text File in a FilePointer Data Item


Writing to a Template in the Template Directory

You can use the Text Writer activity to write Data Item values to a plain text template stored in the Text Template Directory.

Important:

In order to write to a text file in the Template Directory, you must copy the text file to that directory on the process server. By default, the Template Directory is located on the BPM Server in \Program Files\Bluespring\repository\workflow\template\.

After adding a text file to the Template Directory, you need to add the name of the file to the Sys_TextTemplates list.

To write Data Item values to a template in the Template Directory

  1. Add the Text Writer activity to the Canvas and complete the common activity properties.

  2. Click the Text Writer tab.
    The Input File subtab and Output File subtab appear.

  3. Under the Input File subtab, click the Load the template from a file option, and then click the BPM Suite template option.

  4. Click the BPM Suite template drop-down arrow, and then select the template you want to write to.

    Note:
    The list of templates is based on the Sys_TextTemplates list. If you have added a file to the template directory on the server, you also need to add it to the Sys_TextTemplates list in BPM Designer.

  5. Click the Output File subtab.

  6. Determine where to store the completed text.

  7. Saving the Text File to a Data Item

  8. Saving the Text File to a SharePoint Repository

  9. Defining the Text File Name

  7. Click OK.
    The Properties for Activity window closes.

Related Topics

About the Text Writer Activity | Writing to a Template in a Network Location | Writing to a Template in a FilePointer Data Item | Writing to a Template in a SharePoint Repository


About the Word 2007 Form Reader Activity

The Word 2007 Form Reader activity allows you to copy information from Word 2007 form fields to Data Items. The activity supports reading from the new form controls introduced in Word 2007 as well as legacy form controls. Finally, the activity allows you to read file property information about the Word 2007 document, such as the Title, Subject, and Author.

Note:

Microsoft Word 2007 is able to use legacy form controls by treating them like bookmarks. For that reason, this activity is able to look for bookmarks in a Word 2007 document and copy their contents into Data Items.

Preparing a Word 2007 Document to be Read

The Word 2007 Form Reader activity uses a matching system to locate form fields and copy their contents to Data Items. When you create a form control in Word 2007, you need to give it a Name that matches the XML Tag of a Data Item. When the activity reads the document, it will find all matches between Word 2007 form control Names and Data Item XML Tags. The contents of the form fields will be copied into the matching Data Items.

  • Preparing a Word 2007 Document to be Read

Choosing a Word 2007 Document to Read

The Word 2007 document you read can be stored in any one of four possible locations.

  • Reading from a Word 2007 Form in the Template Directory

  • Reading from a Word 2007 Form in a Network Location

  • Reading from a Word 2007 Form in a FilePointer Data Item

  • Reading from a Word 2007 Form in a SharePoint Repository

Reading the File Properties of a Word Document

Regardless of where the file is located, you can read the file properties of the Word document and copy them to Data Items.

  • Reading the Properties of a Word 2007 Document

Required Auxiliary Topics

Before you begin configuring a Word 2007 Form Reader activity, make sure to complete the following:

  • Create Data Items that will store the Word information the activity will read


Preparing a Word 2007 Document to be Read

Rich Text includes text that can be formatted differently within the a single field. It can also include images or other embedded objects (e.g. charts, shapes, clip art, etc.). When reading from a Rich Text control, this activity will copy the entire contents of the form, including all formatting and embedded objects.

Text fields includes only text that has only one formatting (e.g. only bold, only one font, etc.). It does not allow images or other embedded objects. When reading from a Text control, this activity will read the text but will not preserve formatting.

Picture Content fields include only one image. When reading from a Picture Content control, this activity will read the binary data into a FilePointer Data Item. The image will be stored in the BPM Repository as an image file (e.g. as a GIF, a JPG, a BMP, or whatever format the image might be in).

Combo Box fields include drop-down list options and the ability to write your own text in the field rather than select one of the pre-defined options. When reading from a Combo Box, BPM Suite will read the “final text” in the box, whether it is a selected list option or text written in. The text will be stored without any formatting. If the “final text” is one of the pre-defined list options, then the Display Value of the Data Item will be the Display Name of the list option and the Value of the Data Item will be the Value of the list option.

Drop-Down List fields include only the list options that have been defined for the field. When reading from a Drop-Down List control, this activity will read the user-selected list item in the box. The text will be stored in a Data Item without any formatting. The Display Value of the Data Item will be the Display Name of the user-selected list option and the Value of the Data Item will be the Value of the list option.

If the Data Item is associated with a list in List Management, and that list has the same items as the list in the form field, then this activity will set the Data Item to have the same selected list item as the form field.

Date Picker fields include a user-selected date (and, in some cases, also a time). You can map this information to a Data Item three different ways, depending on the format you want the date to have.

Text Data Item

If you map the Date Picker form control to a "Text" Data Item, then you should set the XML value of the Date Picker control to output as "Text". In that case, the Data Item will contain the Date and/or Time in the same format it is displayed through the form field.

Date Data Item

If you map the Date Picker form control to a “Date” Data Item, then you should set the XML value of the Data Picker control to output as "Date". In that case, the Data Item will contain the date in the format DD/MM/YY.

DataTime Data Item

If you map the Date Picker form control to a “DateTime” Data Item, then you should set the XML value of the Data Picker control to output as "Date and Time". In that case, the Data Item will contain the date and time in the format DD/MM/YY HH:MM:SS AM/PM.

Building Block Gallery fields can include any content that is defined as a Building Block in Word 2007. Building Blocks can include any kind of content in any combination. When reading from a Building Block Gallery control, this activity writes the entire content of the Building Block to a Data Item, including any binary data (such as images) that might be present.

Legacy Text fields can contain default text (text that appears in the form before the user enters anything), but they are intended to contain user-defined text. When reading from a legacy Text field, this activity will read the “final text” in the box (i.e. if the default text is still present, that text will be read into the Data Item; if user-defined text is in the control, that text will be read into the Data Item).

Check Boxes can either be checked or unchecked. You can map this information to a Data Item three different ways, depending on how you want to use the information.

Text Data Item

If you map the Check Box form control to a "Text" Data Item, then the Value of Data Item will be set to the number 1 ("checked") or 0 ("not checked"). The Display Value of the Data Item will also be set to "True" (checked) or "False" (not checked).

Boolean Data Item

If you map the Check Box form control to a "Boolean" Data Item, then the same rules apply as they do for a Text Data Item. However, in this case, you can also use the Boolean Data Item to represent a check box in BPM Web.

Sys_YesNo List

If you map the Check Box form control to a Data Item that is associated with the Sys_YesNo list in List Management, then the Data Item will be set to the "Yes" if the checkbox is checked and "No" if the checkbox is not checked.

Drop-Down List fields include only the list options that have been defined for the field. When reading from a Drop-Down List control, this activity will read the user-selected list item in the box. The text will be stored in a Data Item without any formatting. The Display Value of the Data Item will be the Display Name of the user-selected list option and the Value of the Data Item will be the Value of the list option.

If the Data Item is associated with a list in List Management, and that list has the same items as the list in the form field, then this activity will set the Data Item to have the same selected list item as the form field.

Preparing a Word 2007 Document to be Read

Microsoft Word 2007 offers several options for adding form fields to a Word document. The Word 2007 Form Reader activity supports the following Word 2007 form controls:

  • Rich Text

  • Text

  • Picture Content

  • Combo Box

  • Drop-Down List

  • Date Picker

  • Building Block Gallery

In addition to the native Word 2007 form controls, the Word 2007 Form Reader maintains support for some "legacy" form controls available in previous versions of Word:

  • Text

  • Check Box

  • Drop-Down List

Click any of the links above for a description of how the Word 2007 Form Reader will copy the contents of the form control.

To Add the Developer Tab to Word 2007

If you have not already done so, you need to make the Developer tab visible in Word 2007.

  1. Open Microsoft Word 2007.

  2. Click the Application Button (the circle in the upper left-hand corner).

  3. Click Word Options.

  4. Select the Show Developer tab in the Ribbon option, located in the Popular section.

  5. Click OK.
    The Developer tab is now available in the Ribbon.

To Prepare a Form Control to Work with the Word 2007 Form Reader

  1. If you have not already done so, open the process that will use the Word 2007 Form Reader activity in BPM Designer.

  2. If you have not already done so, create Data Items to store the contents of Word 2007 form controls. Make a note of the XML Tags of the Data Items.

  3. Open a Word 2007 document or create a new document.

    Note
    The Word 2007 Form Reader activity only works with Word 2007 documents saved in the .docx format.

  4. Click the Developer tab.

  5. Add a form control to the document.

  6. Click the Properties button. If the Properties button is disabled, make sure the form control you want to set up is selected.
    The Content Control Properties window appears.

  7. Click the Title box and enter the XML Tag of the Data Item that you want to hold the contents of this form control.

  8. If necessary, configure the other properties of the control so that it outputs its data in the format you want. For more information, click the links for each type of form control at the beginning of this article.

  9. Click OK.

To Prepare a Legacy Form Control to Work with the Word 2007 Form Reader

  1. If you have not already done so, open the process that will use the Word 2007 Form Reader activity in BPM Designer.

  2. If you have not already done so, create Data Items to store the contents of Word 2007 form controls. Make a note of the XML Tags of the Data Items.

  3. Open a Word 2007 document or create a new document.

    Note
    The Word 2007 Form Reader activity only works with Word 2007 documents saved in the .docx format.

  4. Click the Developer tab.

  5. Click the Legacy Tools button in the Controls Group.

  6. Add a legacy form control to the document.

  7. Click the Properties button. If the Properties button is disabled, make sure the form control you want to set up is selected.
    The Form Field Options window appears.

  8. Click the Bookmark box and enter the XML Tag of the Data Item that you want to hold the contents of this form control.

  9. If necessary, configure the other properties of the control so that it outputs its data in the format you want. For more information, click the links for each type of form control at the beginning of this article.

  10. Click OK.

Related Topics

About the Word 2007 Form Reader


Reading from a Word 2007 Form in a FilePointer Data Item

You can use the Word 2007 Form Reader activity to read text and other information from a Word document stored in a FilePointer Data Item.

Important:
A FilePointer Data Item is a special type of Data Item. You can read more about storing a file in a Data Item.

To read information from a Word document in a FilePointer Data Item

  1. If you have not already done so, prepare the Word 2007 document to be read.

  2. Add the Word 2007 Form Reader activity to the Canvas and complete the common activity properties.

  3. Click the Word 2007 Form Reader tab.
    The Input File sub-tab is in front.

  4. Select the FilePointer Data Item option.

  5. Click the drop-down list and select the FilePointer Data Item that will contain the Word file you want to read.

  6. Click the Reading Options tab.

  7. Optionally, select the Copy values from Word 2007 form controls option.
    If you select this option, the activity will look for any form controls whose Titles match the XML Tags of Data Items. When it finds an exact match, it will copy the contents of the form control into the Data Item.

    Note
    Refer to the article about preparing a Word 2007 document to be read for more information on this process.

  8. Optionally, select the Copy values from Word 2007 bookmarks option.
    If you select this option, the activity will look for any bookmarks whose Names match the XML Tags of Data Items. When it finds an exact match, it will copy the contents of the bookmark into the Data Item. This function is available because Word 2007 contains legacy form controls in bookmarks.

    Note
    Refer to the article about preparing a Word 2007 document to be read for more information on this process.

  9. Optionally, click the File Properties tab and select Data Items to contain the file property values.

  10. Click OK.
    The Properties window closes.

Related Topics

About the Word 2007 Form Reader Activity | Reading from a Word 2007 Document in the Template Directory | Reading from a Word 2007 Document in a Network Location | Reading from a Word 2007 Document Stored in a SharePoint Repository


Reading from a Word 2007 Form in a Network Location

You can use the Word 2007 Form Reader activity to read text and other information from a Word document stored in a network location.

Important:
The Word 2007 Form Reader activity allows you to select any file accessible to you when you design the process; however, the file also needs to be accessible to the process server when the process runs. For the best results, you should enter the path to the file in UNC format (e.g. \\ComputerName\sharedfolder\filename.extension).

To read information from a Word document in a Network Location

  1. If you have not already done so, prepare the Word 2007 document to be read.

  2. Add the Word 2007 Form Reader activity to the Canvas and complete the common activity properties.

  3. Click the Word 2007 Form Reader tab.
    The Input File sub-tab is in front.

  4. Select the Network file option.

  5. Click in the box and enter the UNC path to the file, or click the Browse button and navigate through your network to find the Word file you want to read.

  6. Click the Reading Options tab.

  7. Optionally, select the Copy values from Word 2007 form controls option.
    If you select this option, the activity will look for any form controls whose Titles match the XML Tags of Data Items. When it finds an exact match, it will copy the contents of the form control into the Data Item.

    Note
    Refer to the article about preparing a Word 2007 document to be read for more information on this process.

  8. Optionally, select the Copy values from Word 2007 bookmarks option.
    If you select this option, the activity will look for any bookmarks whose Names match the XML Tags of Data Items. When it finds an exact match, it will copy the contents of the bookmark into the Data Item. This function is available because Word 2007 contains legacy form controls in bookmarks.

    Note
    Refer to the article about preparing a Word 2007 document to be read for more information on this process.

  9. Optionally, click the File Properties tab and select Data Items to contain the file property values.

  10. Click OK.
    The Properties window closes.

Related Topics

About the Word 2007 Form Reader Activity | Reading from a Word 2007 Document in the Template Directory | Reading from a Word 2007 Document in a FilePointer Data Item | Reading from a Word 2007 Document Stored in a SharePoint Repository


Reading from a Word 2007 Form in a SharePoint Repository

You can use the Word 2007 Form Reader activity to read text and other information from a Word document stored in a SharePoint repository.

Important:
You can enter the address to any file on a SharePoint repository; however, you must have sufficient credentials in order to open the file when the activity runs. When you select your SharePoint site credentials, ensure they have the necessary privileges.

To read information from a Word document in a SharePoint Repository

  1. If you have not already done so, prepare the Word 2007 document to be read.

  2. Add the Word 2007 Form Reader activity to the Canvas and complete the common activity properties.

  3. Click the Word 2007 Form Reader tab.
    The Input File sub-tab is in front.

  4. Select the SharePoint File option.

    • If the entire address to the SharePoint file will be stored in a Data Item, then choose the Select Data Item option.

    • If the address to the SharePoint file will be compiled from multiple Data Items, or if you know the entire address now, then choose the Enter File Path option.

      1. Click the Edit button to open a window that allows you to configure the SharePoint URL.

      2. Click in the URL box to enter the SharePoint URL.

      3. Optionally, click the Data Items drop-down list to select a Data Item that contains part of the SharePoint address, then click the Insert Display Value or Insert Value button to add the Data Item to the URL.

      4. Optionally, click the Preview URL button to see what the URL will look like when the Data Items are replaced with actual values.

      5. Click OK when you are done writing the SharePoint URL.

  5. Select the method by which you wish to specify the SharePoint Server credentials.

    • To use the BPM engine credentials, choose the Use BPM Engine Credentials option, or

    • To manually enter credentials, choose the Enter Credentials option.

      1. Click the Enter Credentials button.

      2. Under the SharePoint username group box:

        • Choose Select Data Item, click the drop-down list, and select the Data Item that will contain the SharePoint username when the process runs, or

        • Choose Enter value and enter the SharePoint username now

      3. Under the SharePoint password group box:

        • Choose Select Data Item, click the drop-down list, and select the Data Item that will contain the SharePoint password when the process runs, or

        • Choose Enter value and enter the SharePoint password now

      4. If your SharePoint site is within a domain, then select the SharePoint Domain check box:

        • Choose Select Data Item, click the drop-down list, and select the Data Item that will contain the SharePoint domain name when the process runs, or

        • Choose Enter value and enter the SharePoint domain name now

      5. Click OK.

  6. Click the Reading Options tab.

  7. Optionally, select the Copy values from Word 2007 form controls option.
    If you select this option, the activity will look for any form controls whose Titles match the XML Tags of Data Items. When it finds an exact match, it will copy the contents of the form control into the Data Item.

    Note
    Refer to the article about preparing a Word 2007 document to be read for more information on this process.

  8. Optionally, select the Copy values from Word 2007 bookmarks option.
    If you select this option, the activity will look for any bookmarks whose Names match the XML Tags of Data Items. When it finds an exact match, it will copy the contents of the bookmark into the Data Item. This function is available because Word 2007 contains legacy form controls in bookmarks.

    Note
    Refer to the article about preparing a Word 2007 document to be read for more information on this process.

  9. Optionally, click the File Properties tab and select Data Items to contain the file property values.

  10. Click OK.
    The Properties window closes.

Related Topics

About the Word 2007 Form Reader Activity | Reading from a Word 2007 Document in the Template Directory | Reading from a Word 2007 Document in a Network Location | Reading from a Word 2007 Document in a FilePointer Data Item


Reading from a Word 2007 Form in the Template Directory

You can use the Word 2007 Form Reader activity to read text and other information from a Word document stored in the BPM Suite Template directory.

Important:
In order to read from a Word document in the Template Directory, you must copy the Word file to that directory on the process server. By default, the Template Directory is located on the BPM Server in C:\Program Files\Bluespring\repository\workflow\template\.

After adding a Word file to the Template Directory, you need to add the name of the file to the Sys_WordTemplates list.

To read information from a Word document in the Template Directory

  1. If you have not already done so, prepare the Word 2007 document to be read.

  2. Add the Word 2007 Form Reader activity to the Canvas and complete the common activity properties.

  3. Click the Word 2007 Form Reader tab.
    The Input File sub-tab is in front.

  4. Select the BPM Suite template option.

  5. Click the drop-down list and select the template from which you want to read.
    Note:     The list of templates is based on the Sys_WordTemplates list. If you have added a file to the template directory on the server, you also need to add it to the Sys_WordTemplates list.

  6. Click the Reading Options tab.

  7. Optionally, select the Copy values from Word 2007 form controls option.
    If you select this option, the activity will look for any form controls whose Titles match the XML Tags of Data Items. When it finds an exact match, it will copy the contents of the form control into the Data Item.

    Note
    Refer to the article about preparing a Word 2007 document to be read for more information on this process.

  8. Optionally, select the Copy values from Word 2007 bookmarks option.
    If you select this option, the activity will look for any bookmarks whose Names match the XML Tags of Data Items. When it finds an exact match, it will copy the contents of the bookmark into the Data Item. This function is available because Word 2007 contains legacy form controls in bookmarks.

    Note
    Refer to the article about preparing a Word 2007 document to be read for more information on this process.

  9. Optionally, click the File Properties tab and select Data Items to contain the file property values.

  10. Click OK.
    The Properties window closes.

Related Topics

About the Word 2007 Form Reader Activity | Reading from a Word 2007 Document in a Network Location | Reading from a Word 2007 Document in a FilePointer Data Item | Reading from a Word 2007 Document in a SharePoint Repository


Reading the Properties of a Word 2007 Document

You can use the Word 2007 Form Reader to read the properties of the Word document into Data Items. The Word 2007 Form Reader supports reading the six basic file properties of Word 2007 documents:

  • Title

  • Subject

  • Author

  • Category

  • Keywords

  • Comments

  1. If you have not already done so, configure the activity to read from a Word document in one of the following locations:

    • Reading from a Word 2007 Form in the Template Directory

    • Reading from a Word 2007 Form in a Network Location

    • Reading from a Word 2007 Form in a FilePointer Data Item

    • Reading from a Word 2007 Form in a SharePoint Repository

  2. Click the File Properties tab.

  3. Click the Value field next to the file property you want to read and select the Data Item that you want to store the file property.

  4. Select Data Items to store all of the file properties that you want to read.

  5. Click OK.
    The Properties window closes.

Related Topics

About the Word 2007 Form Reader Activity


About the Word 2007 Writer Activity

You can use Word 2007 Writer activity to write information from Data Items to a Microsoft Word 2007 document. The Word 2007 Writer can write to a Word 2007 document located in four kinds of locations:

  • The BPM Suite template directory

  • A networked computer

  • A FilePointer Data Item

  • A SharePoint repository

This activity uses Microsoft Word form controls to identify areas of the document that are able to be edited. For that reason, a document usually must be designed to work with the Word 2007 Writer. Be sure to read the section titled Preparing a Word 2007 Document to be Written To for more information.

Note

This activity can write to Word 2007 files even when Word 2007 is not installed on the process server. However, it can only write to Word 2007 files that are saved in the .docx file format.

Follow the links below to view the steps for writing information to Word 2007 documents.

Preparing a Word 2007 Document to be Written To

  • Preparing a Word 2007 Document to be Written To

Choosing a Word Document to Write To

  • Writing to a Word 2007 Document in the Template Directory

  • Writing to a Word 2007 Document in a Network Location

  • Writing to a Word 2007 Document in a FilePointer Data Item

  • Writing to a Word 2007 Document in a SharePoint Repository

Choosing the Location of the Output File

  • Saving the Word 2007 File to a Data Item

  • Saving the Word 2007 File to a SharePoint Repository

  • Defining the Word 2007 Document File Name

Setting the file properties

  • Writing Data Items to the Word File Properties

Required Auxiliary Topics

Before you begin configuring a Word 2007 Writer Activity, make sure to complete the following:

  • Create Data Items that will store the text and images the activity will write


Defining the Word 2007 Document File Name

After you select where to save a Word 2007 file (to a Data Item or to SharePoint), you also need to define a name for the file. The Word file name can be a simple text string or it can be composed of multiple Data Items and/or Non-Data Item values.

To Define the Word Document File Name

  1. Add the Word 2007 Writer activity to the Canvas and complete the common activity properties.

  2. Click the Word 2007 Writer tab.

  3. If you have not already do so, configure the activity to write to an Excel document based in one of the following four locations:

    • Writing to a Word 2007 Document in the Template Directory

    • Writing to a Word 2007 Document in a Network Location

    • Writing to a Word 2007 Document in a FilePointer Data Item

    • Writing to a Word 2007 Document in a SharePoint Repository

  4. Click the Output File tab.

  5. If you have not already done so, configure the activity to save the Excel document to one of the following two locations:

    • Saving the Word 2007 File to a Data Item

    • Saving the Word 2007 File to a SharePoint Repository

  6. Click the Edit button next to the Output file name box. A window that lets you design the file name appears.

  7. If you want to enter static text as the Word file name, then click the File name box and enter text.

  8. If you want to include Data Item values in the Word file name, then select a Data Item in the Available Data Items list and click Insert Display Value or Insert Value.

    Note:     There may be a difference between the Value and the Display Value of a Data Item.

  9. If you want to include a non-Data Item value in the Excel file name, then select one of the options in the Available Non-Data Items list and click Add.

    The File name field shows the final file name with placeholders for all the variables.

  10. Click the Preview File Name button to enter values for the variables and see what the final file name might look like.

  11. Click OK when you're done creating the output file name.

  12. The file name appears in the Output file name field on the Output File tab.

  13. Select the option that corresponds to how you want to handle the Word file if another file with the same name already exists:

    • Select Overwrite the file, if it exists if you want the Word file to overwrite any other files with the same name in the same location.

    • Select Increment the file name, if it exists if you want to add an incrementally higher number to the Word file name rather than overwrite files with the same name. An incrementally higher file name has a number appended to the end. For example, FileName.xls would become FileName-1.xls, and then FileName-2.xls.

  14. Optionally, click the File Properties tab and select Data Items to contain the file property values.

  15. Click OK.
    The Properties window closes.


Preparing a Word 2007 Document to be Written To

Rich Text includes text that can be formatted differently within the a single field. It can also include images or other embedded objects (e.g. charts, shapes, clip art, etc.). When writing to a Rich Text control, this activity will write the entire contents of the form, including all formatting and embedded objects.

Text fields includes only text that has only one formatting (e.g. only bold, only one font, etc.). It does not allow images or other embedded objects. When writing to a Text control, this activity will write plain text and will not preserve formatting.

Picture Content fields include only one image. When writing to a Picture Content control, this activity will write the image file from a FilePointer Data Item into the control.

Combo Box fields include drop-down list options and the ability to write your own text in the field rather than select one of the pre-defined options. For this reason, BPM Suite can write to a Combo Box control from two different kinds of Data Items.

Data Item Connected to a List

If you write to a Combo Box using a Data Item that is associated with a list in List Management, then the list in List Management and the list in the Word 2007 document must be identical. This activity will select the list item in Word 2007 that matches the list item selected in the Data Item.

Text Data Item

If you write to a Combo Box using a Text Data Item, then the Data Item can contain any value--not limited to the options available in the Combo Box in Word. If the Data Item contains a value that matches an option in the Combo Box exactly, then that option will be selected. However, if the Data Item contains a different value, then that value will inserted into the Combo Box as text.

Drop-Down List fields include only the list options that have been defined for the field. When writing to a Drop-Down List field, this activity can write from a Text Data Item or a Data Item associated with a list in List Management.

Text Data Item

If you write from a text Data Item to a Drop-Down list, then the value in the Data Item must exactly match one of the options in the Drop-Down in Word 2007. If the Word 2007 Writer finds an exact match between the Data Item text and an option in the Drop-Down List, then it will select that option.

Data Item Associated with a List

If you write to a Drop-Down List using a Data Item that is associated with a list in List Management, then the list in List Management and the list in the Word 2007 document must be identical. This activity will select the list item in Word 2007 that matches the list item selected in the Data Item.

Date Picker fields include a user-selected date (and, in some cases, also a time). You can write to a Date Picker field three different ways, depending on the type of Data Item you're using to hold the Date.

Text Data Item

If you map a "Text" Data Item to a Date Picker form field, then the Data Item can contain the date and/or time in any format. The Date Picker form will display the contents of the Data Item exactly as it is formatted.

Date Data Item

If you map a "Date" Data Item to the Date Picker form control, then you should set the form control to display the date only (no time). The date in the Data Item will be in the format DD/MM/YY, but the form control can display the date in any of the available options.

DataTime Data Item

If you map a “DateTime” Data Item to the Date Picker form control, then you should set the form control to display the date and time. The date and time in the Data Item will be in the format DD/MM/YY HH:MM:SS, but the form control can display the date and time in any of the available optoins.

Building Block Gallery fields can include any content that is defined as a Building Block in Word 2007. Building Blocks can include any kind of content in any combination. When writing to a Building Block Gallery control, this activity writes the entire content of the Building Block to a Data Item, including any binary data (such as images) that might be present.

When writing to a legacy Text control, this activity will write plain text and will not preserve formatting.

Check Boxes can either be checked or unchecked. You can write to this form control three different ways, depending on how you have captured the information.

Text Data Item

If you map a "Text" Data Item to the form control, it should contain the number 1 ("checked") or 0 ("not checked") as the Value and "True (checked) or "False" (not checked) as the Display Value. The check box will become checked or unchecked based on the value and display value of the Data Item

Boolean Data Item

If you map the Check Box form control to a "Boolean" Data Item, then the same rules apply as they do for a Text Data Item. However, in this case, you can also use the Boolean Data Item to represent a check box in BPM Web.

Sys_YesNo List

If you map the Check Box form control to a Data Item that is associated with the Sys_YesNo list in List Management, then the checkbox will become checked if the Data Item is set to "Yes" and unchecked if the Data Item is set to "No".

Drop-Down List fields include only the list options that have been defined for the field. When writing to a Drop-Down List field, this activity can write from a Text Data Item or a Data Item associated with a list in List Management.

Text Data Item

If you write from a text Data Item to a Drop-Down list, then the value in the Data Item must exactly match one of the options in the Drop-Down in Word 2007. If the Word 2007 Writer finds an exact match between the Data Item text and an option in the Drop-Down List, then it will select that option.

Data Item Associated with a List

If you write to a Drop-Down List using a Data Item that is associated with a list in List Management, then the list in List Management and the list in the Word 2007 document must be identical. This activity will select the list item in Word 2007 that matches the list item selected in the Data Item.

Preparing a Word 2007 Document to be Written To

Microsoft Word 2007 offers several options for adding form fields to a Word document. The Word 2007 Writer activity supports the following Word 2007 form controls:

  • Rich Text

  • Text

  • Picture Content

  • Combo Box

  • Drop-Down List

  • Date Picker

  • Building Block Gallery

In addition to the native Word 2007 form controls, the Word 2007 Writer maintains support for some "legacy" form controls available in previous versions of Word:

  • Text

  • Check Box

  • Drop-Down List

Click any of the links above for a description of how the Word 2007 Writer will write information to the form control.

To Add the Developer Tab to Word 2007

If you have not already done so, you need to make the Developer tab visible in Word 2007.

  1. Open Microsoft Word 2007.

  2. Click the Application Button (the circle in the upper left-hand corner).

  3. Click Word Options.

  4. Select the Show Developer tab in the Ribbon option, located in the Popular section.

  5. Click OK.
    The Developer tab is now available in the Ribbon.

To Prepare a Form Control to Work with the Word 2007 Form Reader

  1. If you have not already done so, open the process that will use the Word 2007 Form Reader activity in BPM Designer.

  2. If you have not already done so, create Data Items to store the contents of Word 2007 form controls. Make a note of the XML Tags of the Data Items.

  3. Open a Word 2007 document or create a new document.

    Note
    The Word 2007 Form Reader activity only works with Word 2007 documents saved in the .docx format.

  4. Click the Developer tab.

  5. Add a form control to the document.

  6. Click the Properties button. If the Properties button is disabled, make sure the form control you want to set up is selected.
    The Content Control Properties window appears.

  7. Click the Title box and enter the XML Tag of the Data Item that you want to hold the contents of this form control.

  8. Click the Tag box and enter Value or DisplayValue.

    • Entering Value will instruct the Word 2007 Writer to write the Value of the Data Item to the form field

    • Entering DisplayValue will instruct the Word 2007 Writer to write the Display Value of the Data Item to the form field

  9. If necessary, configure the other properties of the control so that it outputs its data in the format you want. For more information, click the links for each type of form control at the beginning of this article.

  10. Click OK.

To Prepare a Legacy Form Control to Work with the Word 2007 Form Reader

  1. If you have not already done so, open the process that will use the Word 2007 Form Reader activity in BPM Designer.

  2. If you have not already done so, create Data Items to store the contents of Word 2007 form controls. Make a note of the XML Tags of the Data Items.

  3. Open a Word 2007 document or create a new document.

    Note
    The Word 2007 Form Reader activity only works with Word 2007 documents saved in the .docx format.

  4. Click the Developer tab.

  5. Click the Legacy Tools button in the Controls Group.

  6. Add a legacy form control to the document.

  7. Click the Properties button. If the Properties button is disabled, make sure the form control you want to set up is selected.
    The Form Field Options window appears.

  8. Click the Bookmark box and enter the XML Tag of the Data Item that you want to hold the contents of this form control.

  9. If necessary, configure the other properties of the control so that it outputs its data in the format you want. For more information, click the links for each type of form control at the beginning of this article.

  10. Click OK.

Related Topics

About the Word 2007 Form Reader


Saving the Word 2007 File to a Data Item

You can use the Word 2007 Writer activity to save a Word file in two different ways. You can save a Word file to a FilePointer Data Item or you can save it to a SharePoint repository. You might want to save a Word document to a Data Item if you plan to manipulate it multiple times throughout a process, or if you do not use SharePoint. You might want to save the file to SharePoint if you want to make the file available to people outside the context of the process and so that SharePoint can maintain a repository of your files.

To save a Word 2007 file to a Data Item

  1. Add the Word 2007 Writer activity to the Canvas and complete the common activity properties.

  2. Click the Word 2007 Writer tab.

  3. If you have not already do so, configure the activity to write to a Word document based in one of the following four locations:

    • Writing to a Word 2007 Document in the Template Directory

    • Writing to a Word 2007 Document in a Network Location

    • Writing to a Word 2007 Document in a FilePointer Data Item

    • Writing to a Word 2007 Document in a SharePoint Repository

  4. Click the Output File tab.

  5. Select the Output file to a Data Item option.

  6. Click the Data Item to store output file drop-down list and select the FilePointer Data Item that you want to hold the Word document after the activity writes to it.

    Note:     Only FilePointer Data Items appear in this list.

  7. Define a file name for the Word document.

  8. Click the Data Items tab.

  9. Optionally, click the File Properties tab and select Data Items to contain the file property values.

  10. Click OK.
    The Properties window closes.


Saving the Word 2007 File to a SharePoint Repository

You can use the Word 2007 Writer activity to save a Word document in two different ways. You can save a Word document to a FilePointer Data Item or you can save it to a SharePoint repository. You might want to save a Word file to a Data Item if you plan to manipulate it multiple times throughout a process, or if you do not use SharePoint. You might want to save the file to SharePoint if you want to make the file available to people outside the context of the process and so that SharePoint can maintain a repository of your files.

To save a Word document to a SharePoint Repository

  1. Add the Word 2007 Writer activity to the Canvas and complete the common activity properties.

  2. Click the Word 2007 Writer tab.

  3. If you have not already done so, configure the activity to write to a Word document based in one of the following four locations:

    • Writing to a Word 2007 Document in the Template Directory

    • Writing to a Word 2007 Document in a Network Location

    • Writing to a Word 2007 Document in a FilePointer Data Item

    • Writing to a Word 2007 Document in a SharePoint Repository

  4. Click the Output File tab.

  5. Select the Output file to SharePoint option.

    • If the entire address to the SharePoint file will be stored in a Data Item, then choose the Select Data Item option. Click the drop-down list and select the Data Item that will contain the address to SharePoint location where you want to save the file.

    • If the address to the SharePoint file should be compiled from multiple Data Items, or if you know the entire address now, then choose the Enter file path option.

      1. Click the Edit button to open a window that allows you to configure the SharePoint URL.

      2. Click in the URL box to enter the SharePoint URL.

      3. Optionally, click the Data Items drop-down list to select a Data Item that contains part of the SharePoint address, then click the Insert Display Value or Insert Value button to add the Data Item to the URL.

      4. Optionally, click the Preview URL button to see what the URL will look like when the Data Items are replaced with actual values.

      5. Click OK when you are done writing the SharePoint URL.

  6. If the location on SharePoint where you want to save the file might not already exist when the activity runs, you can select the Create directory if it does not exist option. If you select this option, the Word 2007 Writer activity will create any directories as necessary to save the file in the specified location.

    Note:     If you do not select this option, and the activity attempts to save a file in a location that does not exist, then the activity will generate an error. The process will still continue.

  7. Click the Enter Credentials button.

  8. Under the SharePoint username group box:

    • Choose Select Data Item, click the drop-down list, and select the Data Item that will contain the SharePoint username when the process runs, or

    • Choose Enter value and enter the SharePoint username now

  9. Under the SharePoint password group box:

    • Choose Select Data Item, click the drop-down list, and select the Data Item that will contain the SharePoint password when the process runs, or

    • Choose Enter value and enter the SharePoint password now

  10. If your SharePoint site is within a domain, then select the SharePoint Domain check box:

    • Choose Select Data Item, click the drop-down list, and select the Data Item that will contain the SharePoint domain name when the process runs, or

    • Choose Enter value and enter the SharePoint domain name now

  11. Click OK.

  12. If you want to save the entire path to the file (including the file name) after it has been saved in SharePoint, you can select the Store the complete file path (including file name) in a Data Item option. After you select that option, the drop-down list will become enabled and you will be able to select the Data Item that you want to contain the complete file path.

  13. Define a file name for the Word file.

  14. Optionally, click the File Properties tab and select Data Items to contain the file property values.

  15. Click OK.
    The Properties window closes.


Writing Data Items to the Word File Properties

You can use this option in the Word 2007 Writer activity to add metadata information to the properties of the Word file.

To Write Data Item values to the Word File Properties

  1. Add the Word 2007 Writer activity to the Canvas and complete the common activity properties.

  2. Click the Word 2007 Writer tab.

  3. If you have not already done so, configure the activity to write to a Word document based in one of the following four locations:

    • Writing to a Word 2007 Document in the Template Directory

    • Writing to a Word 2007 Document in a Network Location

    • Writing to a Word 2007 Document in a FilePointer Data Item

    • Writing to a Word 2007 Document in a SharePoint Repository

  4. If you have not already done so, determine where the completed Word document will be stored and what its file name will be.

    • Saving the Word 2007 File to a Data Item

    • Saving the Word 2007 File to a SharePoint Repository

    • Defining the Word 2007 Document File Name

  5. Click the File Properties tab.

  6. Find the file property you want to set, located in the File Property column.

  7. Click the Source cell for that property and select Constant, .DisplayValue, or .Value.

    Select Constant if you want to enter the value for the file property now and use the same value every time the activity runs.
    Select .DisplayValue if you want to use the Display Value of the Data Item.
    Select .Value if you want to use the Value of the Data Item.

  8. Repeat steps 6-8 for each file property you want to set.

  9. Click OK.
    The Properties window closes.

Related Topics

About the Word 2007 Writer Activity


Writing to a Word 2007 Document in a FilePointer Data Item

You can use the Word 2007 Writer activity to write Data Item values to a Word document stored in a FilePointer Data Item. For more information on FilePointer Data Items, refer to the article titled Storing a File in a Data Item.

To write Data Item values to a Word document in a FilePointer Data Item

  1. Add the Word 2007 Writer activity to the Canvas and complete the common activity properties.

  2. Click the Word 2007 Writer tab.
    The Input File sub-tab is in front.

  3. Select the FilePointer Data Item option.

  4. Click the drop-down list and select the FilePointer Data Item that contains the Word 2007 document you want to modify.

    Note:     Only FilePointer Data Items appear in this list.

  5. Determine where the completed Word document will be stored and what its file name will be.

    • Saving the Word File to a Data Item

    • Saving the Word File to a SharePoint Repository

    • Defining the Word File Name

  6. Optionally, click the File Properties tab and select Data Items to contain the file property values.

  7. Click OK.
    The Properties window closes.

Related Topics

About the Word 2007 Writer Activity | Writing to an Word 2007 Document in a Network Location | Writing to an Word 2007 Document in the Template Directory | Writing to an Word 2007 Document in a SharePoint Repository


Writing to a Word 2007 Document in a Network Location

You can use the Word 2007 Writer activity to write Data Item values to a Word document stored in any accessible location within your network. The file you select must be accessible to the server that hosts BPM Server when the process runs. It is probably easiest to find a file within your network if that file is in a shared directory. Contact your system administrator if you need help setting up a shared directory in Windows.

To write Data Item values to a Word document in a Network Location

  1. Add the Word 2007 Writer activity to the Canvas and complete the common activity properties.

  2. Click the Word 2007 Writer tab.
    The Input File sub-tab is in front.

  3. Select the Network file option.

  4. If you already know the location of the file that you want to write to, you can enter the file path in the text box. If you want to navigate to the file, then click the Browse button to open a window that will show you all the computers on your network. Click OK after you select the file you want to write to.

    Note:     If you enter the path to the file manually, then you should enter it in UNC format. In most situations, the computer you use to design the process is not the same as the server that executes the process, so a local path (such as one that begins with C:\) will point to a different location on different computers.

  5. Click the Output File tab.

  6. Determine where the completed Word document will be stored and what its file name will be.

    • Saving the Word 2007 File to a Data Item

    • Saving the Word 2007 File to a SharePoint Repository

    • Defining the Word 2007 Document File Name

  7. Optionally, click the File Properties tab and select Data Items to contain the file property values.

  8. Click OK.
    The Properties window closes.

Related Topics

About the Word 2007 Writer Activity | Writing to a Word 2007 Document in the Template Directory | Writing to a Word 2007 Document in a FilePointer Data Item | Writing to a Word 2007 Document in a SharePoint Repository


Writing to a Word 2007 Document in a SharePoint Repository

You can use the Word 2007 Writer activity to write Data Item values to a Word document stored in a SharePoint repository.

Important:
You can enter the address to any file on a SharePoint repository; however, you must have sufficient credentials in order to open the file when the activity runs. When you select your SharePoint site credentials, ensure they have the necessary privileges.

To write Data Item values to a Word document in a SharePoint Repository

  1. Add the Word 2007 Writer activity to the Canvas and complete the common activity properties.

  2. Click the Word 2007 Writer tab.
    The Input File sub-tab is in front.

  3. Select the SharePoint file option.

    • If the entire address to the SharePoint file will be stored in a Data Item, then choose the Select Data Item option. Click the drop-down list and select the Data Item that will contain the address to the file on SharePoint.

    • If the address to the SharePoint file will be compiled from multiple Data Items, or if you know the entire address now, then choose the Enter File Path option.

      1. Click the Edit button to open a window that allows you to configure the SharePoint URL.

      2. Click in the URL box to enter the SharePoint URL.

      3. Optionally, click the Data Items drop-down list to select a Data Item that contains part of the SharePoint address, then click the Insert Display Value or Insert Value button to add the Data Item to the URL.

      4. Optionally, click the Preview URL button to see what the URL will look like when the Data Items are replaced with actual values.

      5. Click OK when you are done writing the SharePoint URL.

  4. Select the method by which you wish to specify the SharePoint Server credentials.

    • To use the BPM engine credentials, choose the Use BPM Engine Credentials option, or

    • To manually enter credentials, choose the Enter Credentials option.

      1. Click the Enter Credentials button.

      2. Under the SharePoint username group box:

        • Choose Select Data Item, click the drop-down list, and select the Data Item that will contain the SharePoint username when the process runs, or

        • Choose Enter value and enter the SharePoint username now

      3. Under the SharePoint password group box:

        • Choose Select Data Item, click the drop-down list, and select the Data Item that will contain the SharePoint password when the process runs, or

        • Choose Enter value and enter the SharePoint password now

      4. If your SharePoint site is within a domain, then select the SharePoint Domain check box:

        • Choose Select Data Item, click the drop-down list, and select the Data Item that will contain the SharePoint domain name when the process runs, or

        • Choose Enter value and enter the SharePoint domain name now

      5. Click OK.

  5. Determine where the completed Word document will be stored and what its file name will be.

    • Saving the Word 2007 File to a Data Item

    • Saving the Word 2007 File to a SharePoint Repository

    • Defining the Word 2007 Document File Name

  6. Optionally, click the File Properties tab and select Data Items to contain the file property values.

  7. Click OK.
    The Properties window closes.

Related Topics

About the Word 2007 Writer Activity | Writing to a Word 2007 Document in a Network Location | Writing to a Word 2007 Document in the Template Directory | Writing to a Word 2007 Document in a FilePointer Data Item


Writing to a Word 2007 Document in the Template Directory

You can use the Word 2007 Writer activity to write Data Item values to a Word document stored in the Word Template Directory.

Important:
In order to write to a Word document in the Template Directory, you must copy the Word file to that directory on the process server. By default, the Template Directory is located on the BPM Server in C:\Program Files\Bluespring\repository\workflow\template\.

After adding a Word file to the Template Directory, you need to add the name of the file to the Sys_WordTemplates list.

To write Data Item values to a Word document in the Template Directory

  1. Add the Word 2007 Writer activity to the Canvas and complete the common activity properties.

  2. Click the Word 2007 Writer tab.
    The Input File sub-tab is in front.

  3. Select the BPM Suite template option.

  4. Click the drop-down list and select the template to which you want to write.
    Note:     The list of templates is based on the Sys_WordTemplates list. If you have added a file to the template directory on the server, you also need to add it to the Sys_WordTemplates list.

  5. Click the Output File tab.

  6. Determine where the completed Word document will be stored and what its file name will be.

    • Saving the Word 2007 File to a Data Item

    • Saving the Word 2007 File to a SharePoint Repository

    • Defining the Word 2007 Document File Name

  7. Optionally, click the File Properties tab and select Data Items to contain the file property values.

  8. Click OK.
    The Properties window closes.

Related Topics

About the Word 2007 Writer Activity | Writing to a Word 2007 Document in a Network Location | Writing to a Word 2007 Document in a FilePointer Data Item | Writing to a Word 2007 Document in a SharePoint Repository


About the Word Activity

About the Word Writer Activity

Using a Word Writer activity, you can write information stored in Data Items to Microsoft Word document templates. When the Word Writer activity executes, it will look through your Word document template for %DataItem.Value% and %DataItem.DisplayValue% and replace them with the appropriate Data Item value or display value.

Example:

Before: Company Name: %CompanyName.DisplayValue%
After: Company Name: Bluespring Software, Inc.

Follow the links below to view instructions on populating Word templates with Data Items.

  • Populating a Word File from the Template Directory with Data Item Values

  • Populating a Word File from a Network Location with Data Item Values

  • Populating a Word File from a FilePointer Data Item with Data Item Values

Required Auxiliary Topics

Before you can use a Word template in the Word activity, you must add the Word template to BPM Designer's Word template directory.

  • Adding a Word File to the Template Directory

Also, you will need to create Data Items that will store the information you want to use to populate the Word template.

  • Creating Data Items


If a file with the same name exists in the same folder as the output file, then that file will be overwritten by the new file.

If a file with the same name exists in the same folder as the output file, then the activity will increment the output file name by adding a dash ( - ) and a number to the end of it.

Example:
file-1.doc).

Populating a Word File from a FilePointer Data Item with Data Item Values

With the Word Writer activity, you have the option of retrieving a Word file to write to from a FilePointer Data Item.

To populate a Word file from a FilePointer Data Item with Data Items

  1. Add the Word activity to the Canvas and complete the common activity properties.

    Note:
    Completing common activity properties is essential to create an organized and functional process.

  2. Click the Word Writer tab.

  3. Under the Input file source section, select the Use existing file in FilePointer Data Item option.
    The drop-down list below the selection becomes enabled.

  4. Using the drop-down list, select a FilePointer Data Item that contains the Word file you want to populate.

  5. Under the Output file Data Item and name section, using the Data Item to store output file drop-down list, select the FilePointer Data Item that you want to store the populated Word document.

  6. In the Output file name field, enter a name for the output file.

    Note:
    To include a file type, enter a file extension into the file name.

    Example:
    example.txt     will be a Text document

  7. Optional: Click the Edit button to set the output file name

  8. Using the Output file save as type drop-down list, select the type of file that you want the output file to be.

  9. Optional: Un-check the Add extension checkbox

    Note:
    Un-check the Add extension checkbox if you want the Output file save as type extension to be the extension of the file name you entered. If the checkbox is checked, then the extension is added to whatever extension you specified in the file name.

    Example:
    If you entered example.txt as the file name and selected Microsoft Word (*doc), the activity will name the output file example.doc at run-time if the Add Extension checkbox is un-checked. If it is checked the file name will be example.txt.doc.

  10. Under File replacement options, select one of the two following options:

    • Overwrite output file if it exists

    • Increment file name if it exists

  11. Click the Find & Replace Settings tab.

  12. Click the arrow buttons to add or remove Data Items from the Available Data Items list to the Selected Data Items list.
    When this Word Writer activity executes, it will only look for the Data Items you add to the Selected Data Items list, which enables the activity to run more quickly by not having to search for each available Data Item.

  13. Click the OK button.
    The Properties for Activity window closes.

Related Topics

Populating a Word File from a Network Location with Data Item Values | Populating a Word File from the Template Directory with Data Item Values | Adding a Word File to a Template Directory


Populating a Word File from a Network Location with Data Item Values

The path can be either a URL (http://...) or a network address (\\<computerName>\<folderName>\<fileName>).

Note:
The path must specify a file that is at a network location that BPM Engine can access.

Through the file browse window, search for and select a file. After you select a file, the activity will automatically generate the path necessary to retrieve the file and it will display the path in the field, in the main activity window.

Note:
The file you select must be at a network location that BPM Engine can access.

If a file with the same name exists in the same folder as the output file, then that file will be overwritten by the new file.

If a file with the same name exists in the same folder as the output file, then the activity will increment the output file name by adding a dash ( - ) and a number to the end of it (Example: file-1.doc).

Populating a Word File from a Network Location with Data Item Values

If the Word file you want to write to is not in the template directory and will not come from a FilePointer Data Item, you can select a file from any network location that BPM Engine can access. At run-time, the activity will retrieve the file you specify.

To populate a Word file from a Network Location with Data Items

  1. Add the Word activity to the designer canvas and complete the common activity properties.

  2. Click the Word Writer tab.

  3. Under the Input file source section, select the Select template file from other location option.
    The field and button below the selection become enabled.

  4. Perform one of the following actions:

    • Enter the path to the location of the word file you want the activity to populate

    • Browse for the path through a browse window

  5. Under the Output file Data Item and name section, using the Data Item to store output file drop-down list, select the FilePointer Data Item that you want to store the populated Word document.

  6. In the Output file name field, enter a name for the output file.

    Note:
    To include a file type, enter a file extension into the file name.

    Example:
    example.txt     will be a Text document

  7. Optional: Click the Edit button to set the output file name

  8. Using the Output file save as type drop-down list, select the type of file that you want the output file to be.

  9. Optional: Un-check the Add extension checkbox

    Note:
    Un-check the Add extension checkbox if you want the Output file save as type extension to be the extension of the file name you entered. If the checkbox is checked, then the extension is added to whatever extension you specified in the file name.

    Example:
    If you entered example.txt as the file name and selected Microsoft Word (*doc), the activity will name the output file example.doc at run-time if the Add Extension checkbox is un-checked. If it is checked the file name will be example.txt.doc.

  10. Under File replacement options, select one of the two following options:

    • Overwrite output file if it exists

    • Increment file name if it exists

  11. Click the Find & Replace Settings tab.

  12. Click the arrow buttons to add or remove Data Items from the Available Data Items list to the Selected Data Items list.
    When this Word activity executes, it will only look for the Data Items you add to the Selected Data Items list, which enables the activity to run more quickly by not having to search for each available Data Item.

  13. Click the OK button.
    The Properties for Activity window closes.

Related Topics

Populating a Word File from a FilePointer Data Item with Data Item Values | Populating a Word File from the Template Directory with Data Item Values | Adding a Word File to a Template Directory


If a file with the same name exists in the same folder as the output file, then that file will be overwritten by the new file.

If a file with the same name exists in the same folder as the output file, then the activity will increment the output file name by adding a dash ( - ) and a number to the end of it (Example: file-1.doc).

Populating a Word File from the Template Directory with Data Item Values

If there is a Word template in BPM Suite's Word template directory, then you can populate it with Data Items using the Word activity.

Important:
Word templates must be added to and stored in the Remote Server Repository folder, which by default is located on the BPM Server in C:\Bluespring\workflow\template\<file name>.

After adding a template to the Remote Server Repository folder, you need to add the name of the file to the Sys_WordTemplates list.

To populate a Word file from the Template Directory with Data Items

  1. Add the Word activity to the Canvas and complete the common activity properties.

  2. Click the Word Writer tab.

  3. Under the Input file source section, using the Select template file from Template directory drop-down list, select a Word template.

  4. Under the Output file Data Item and name section, using the Data Item to store output file drop-down list, select the FilePointer Data Item that you want to store the populated Word document.

  5. In the Output file name field, enter a name for the output file.

    Note:
    To include a file type, enter a file extension into the file name.

    Example:
    example.txt     will be a Text document

  6. Optional: Click the Edit button to set the output file name

  7. Using the Output file save as type drop-down list, select the type of file that you want the output file to be.

  8. Optional: Un-check the Add extension checkbox

    Note:
    Un-check the Add extension checkbox if you want the Output file save as type extension to be the extension of the file name you entered. If the checkbox is checked, then the extension is added to whatever extension you specified in the file name.

    Example:
    If you entered example.txt as the file name and selected Microsoft Word (*doc), the activity will name the output file example.doc at run-time if the Add Extension checkbox is un-checked. If it is checked the file name will be example.txt.doc.

  9. Under File replacement options, select one of the two following options:

    • Overwrite output file if it exists

    • Increment file name if it exists

  10. Click the Find & Replace Settings tab.

  11. Click the arrow buttons to add or remove Data Items from the Available Data Items list to the Selected Data Items list.
    When this Word activity executes, it will only look for the Data Items you add to the Selected Data Items list, which enables the activity to run more quickly by not having to search for each available Data Item.

  12. Click the OK button.
    The Properties for Activity window closes.

Related Topics

Populating a Word File from a FilePointer Data Item with Data Item Values | Populating a Word File from a Network Location with Data Item Values | Adding a Word File to a Template Directory


CAP - Desktop Activities

  1. Click the Desktop Activities category in the Process Designer toolbox.

  2. Double-click the activity you want to add, or drag it to the Canvas.
    The activity is added to the process.

  3. Open the Properties for the activity (double-click the activity or right-click and select Activity Properties).
    The Properties window appears.

  4. Complete the common activity properties.


About the Create Live Meeting Activity

You can use the Create Live Meeting activity to create a scheduled meeting, define a subject for the meeting, invite attendees, and select the start time. You can also set a variety of other meeting options, and record the values that are automatically generated when the meeting is created. However, the Create Live Meeting activity does not support Meet Now meetings (i.e. non-scheduled meetings).

  • Creating a Live Meeting

Required Auxiliary Topics

Before you begin configuring the Create Live Meeting activity, make sure to complete the following:

  • Create Data Items that will store meeting values and settings.


Creating a Live Meeting

A Live Meeting is a group conference that involves a shared phone line and may also involve application sharing. You can use the Create Live Meeting activity to create a Live Meeting, invite attendees and presenters, and set meeting options.

To create a Live Meeting

  1. Add the Create Live Meeting activity to the Canvas and complete the common activity properties.

  2. Click the Create Live Meeting tab.

  3. Set up the Organizer Information.

  4. Click the Schedule Meeting tab.

  5. Under Meeting subject, click the Subject field and enter a brief description of the meeting topic.

    You can also click the Data Items drop-down list and select a Data Item that will contain part or all of the subject line. Click Add to Subject to use the Data Item in the subject line.

  6. Under Meeting attendees and presenters, click the Attendees field and enter the email addresses of the people you want to invite to attend the meeting.

    You can also click the Data Items drop-down list and select a Data Item that will contain one or more email addresses or a BPM User ID. Click Add as Attendee to invite those people to attend the meeting. If you selected a Data Item that contains a BPM User ID, BPM Suite will look up the User's email address and use that for the invitation.

    Note:
    Multiple email addresses should be separated with semi-colons.

  7. Click the Presenters field and enter the email addresses of the people you want to invite to present at the meeting.

    You can also click the Data Items drop-down list and select a Data Item that will contain one or more email addresses or a BPM User ID. Click Add as Presenter to invite those people to attend the meeting. If you selected a Data Item that contains a BPM User ID, BPM Suite will look up the User's email address and use that for the invitation.

    Note:
    Multiple email addresses should be separated with semi-colons.

  8. Click the up and down arrows on the Meeting size field to select the number of people who you want to attend the meeting.
    For example, if you invite 30 people, but set the meeting size to 10 people, only the first 10 people will be allowed to join.
    Also, your "conference center" (your Live Meeting account) may allow only a limited number of people to be in a meeting at once. If you set the meeting size to a number greater than the number of available seats, the Create Live Meeting activity will fail.

  9. Under Meeting date and time, choose either Select Data Item or Enter date and time.

    If you choose Select Data Item, click the drop-down list and select the Data Item that contains the date and time when the meeting should start.

    Note:
    The Data Item does not have to be of the type DateTime; however, it does have to be in the following format: MM/DD/YY HH:MM AM/PM (e.g. 07/21/06 3:00 PM).

    If you choose Enter date and time, use the drop-down lists to select the date and time when the meeting should start.

    Note:
    The Create Live Meeting activity will convert the time you enter to UTC time, so all participants will see the correct time for their time zone.

  10. Optionally, you can click the End date/time option to enter the ending date and time for the meeting.

    Set the end date/time exactly like you set the start date/time.

  11. Click the Meeting Options & Return Fields tab.

  12. Under Meeting options, click the Option Name field and select an option that you want to define for this meeting.
    The Type field changes to reflect the type of value required by the option you selected.

  13. Click the Source field and select Value, Display Value, or Constant.

    If you selected Value, the Value field will use the value of the Data Item you select.
    If you selected Display Value, the Value field will use the display value of the Data Item you select.
    If you selected Constant, you will be able to enter the value you want to use at design time.

  14. Click the Value field and enter the value you want to submit for the selected option, or select the Data Item that will contain that value at run time.

  15. Repeat steps 12 - 14 to set as many meeting options as necessary.

  16. Under Return fields, click the Data Item field and select the Data Item that you want to hold the value of some meeting option. For example, if you want to store the Meeting ID, you might select a Data Item called "MeetingID".

  17. Click the Return Field field and select the meeting option whose value you want to store. The value set for that meeting option will be stored in the Data Item you selected.

    Note:
    The most common meeting options that you may want to return are Meeting ID (mid), Audience Password (audiencePassword), and Presenter Password (presenterPassword). At the very least, you should save the Meeting ID to a Data Item so you can access this meeting in later activities and send the Meeting ID to attendees.

  18. Select the Clear Existing Values option if you want the Data Item to contain only the value of that meeting option, or unselect that option if you want to add the value of the meeting option to any other values that may already be in the Data Item.

  19. Repeat steps 16 - 18 to store as many meeting values as necessary.

  20. Click OK.
    The Properties window closes.


About the Delete Live Meeting Activity

You can use the Delete Live Meeting activity to remove Live Meetings that you have already created. For example, if you create a Live Meeting, but later find out that some important attendees cannot attend, you might want to cancel the meeting. You can automate that kind of situation by using the Delete Live Meeting activity.

  • Deleing a Live Meeting

Required Auxiliary Topics

Before you begin configuring the Delete Live Meeting activity, make sure to complete the following:

  • Create Data Items that will store meeting values and settings.


Deleting a Live Meeting

A Live Meeting is a group conference that involves a shared phone line and may also involve application sharing. You can use the Delete Live Meeting activity to delete a Live Meeting that you already created.

To delete a Live Meeting

  1. Add the Delete Live Meeting activity to the Canvas and complete the common activity properties.

  2. Click the Delete Live Meeting tab.

  3. Set up the Organizer Information.

  4. Click the Meeting to Delete tab.

  5. Under Meeting to delete, choose either Select Data Item or Enter value.

    If you choose Select Data Item, click the drop-down list and select the Data Item that will contain the Meeting ID of the Live Meeting you want to delete.
    If you choose Enter value, enter the Meeting ID of the Live Meeting you want to delete.

  6. Optionally, select the Save error message option, click the Data Item field and select the Data Item that you want to store the error message.
    If Live Meeting returns an when you delete the meeting, this Data Item will store the text of that error message.

  7. Click OK.
    The Properties window closes.


About the Retrieve Live Meeting Activity

You can use the Retrieve Live Meeting activity to retrieve information about Live Meetings that you have created. You can retrieve information about a specific Live Meeting, or about all Live Meetings within a range of dates. You can also retrieve information about meetings that have been deleted.

  • Retrieving a Specific Live Meeting

  • Retrieving all Live Meetings within a Date Range

Required Auxiliary Topics

Before you begin configuring the Retrieve Live Meeting activity, make sure to complete the following:

  • Create Data Items that will store meeting values and settings.


Retrieving a Specific Live Meeting

You can use the Retrieve Live Meeting activity to retrieve information about any meeting you have created.

Note:
You can only retrieve information about meetings that were created with the Live Meeting User ID that you select when you set up the Organizer Information. However, if you enter the User ID of an Administrator, you can retrieve information about any meeting.

To retrieve a specific Live Meeting

  1. Add the Retrieve Live Meeting activity to the Canvas and complete the common activity properties.

  2. Click the Retrieve Live Meeting tab.

  3. Set up the Organizer Information.

  4. Click the Meeting(s) to Retrieve tab.

  5. Select the Retrieve specific meeting option.

  6. Choose either Select Data Item or Enter value.

    If you choose Select Data Item, click the drop-down list and select the Data Item that will contain the Meeting ID of the Live Meeting whose information you want to retrieve.
    If you choose Enter value, enter the Meeting ID of the Live Meeting whose information you want to retrieve.

  7. Optionally, select the Include deleted meetings in search results option to retrieve information about that meeting even if it has been deleted.

  8. Click the Meeting Options to Retrieve tab.

  9. Under Meeting options, click the Data Item field and select the Data Item that you want to hold the value of some meeting option. For example, if you want to store the Meeting ID, you might select a Data Item called "MeetingID".

  10. Click the Return Field field and select the meeting option whose value you want to store. The value set for that meeting option will be stored in the Data Item you selected.

    Note:
    The most common meeting options that you may want to return are Meeting ID (mid), Audience Password (audiencePassword), and Presenter Password (presenterPassword). At the very least, you should save the Meeting ID to a Data Item so you can access this meeting in later activities and send the Meeting ID to attendees.

  11. Select the Clear Existing Values option if you want the Data Item to contain only the value of that meeting option, or unselect that option if you want to add the value of the meeting option to any other values that may already be in the Data Item.

  12. Repeat steps 9 - 11 to store as many meeting values as necessary.

  13. Optionally, select the Save error message, click the Data Item field and select the Data Item that you want to store the error message.
    If Live Meeting returns an when you delete the meeting, this Data Item will store the text of that error message.

  14. Click OK.
    The Properties window closes.


Retrieving All Live Meetings Within a Date Range

You can use the Retrieve Live Meeting activity to retrieve information about all meetings that happened or will happen within a specified range of dates.

Note:
You can only retrieve information about meetings that were created with the Live Meeting User ID that you select when you set up the Organizer Information. However, if you enter the User ID of an Administrator, you can retrieve information about any meeting.

To retrieve a specific Live Meeting

  1. Add the Retrieve Live Meeting activity to the Canvas and complete the common activity properties.

  2. Click the Retrieve Live Meeting tab.

  3. Set up the Organizer Information.

  4. Click the Meeting(s) to Retrieve tab.

  5. Select the Retrieve meetings in a date range option.

  6. Under Start date/time, choose either Select Data Item or Enter value.

    If you choose Select Data Item, click the drop-down list and select the Data Item that contains the beginning date and time in the range you want to search.

    Note:
    The Data Item does not have to be of the type DateTime; however, it does have to be in the following format: MM/DD/YY HH:MM AM/PM (e.g. 07/21/06 3:00 PM).

    If you choose Enter date and time, use the drop-down lists to select the beginning date and time in the range you want to search.

  7. Under End date/time, choose either Select Data Item or Enter value.

    If you choose Select Data Item, click the drop-down list and select the Data Item that contains the end date and time in the range you want to search.

    Note:
    The Data Item does not have to be of the type DateTime; however, it does have to be in the following format: MM/DD/YY HH:MM AM/PM (e.g. 07/21/06 3:00 PM).

    If you choose Enter date and time, use the drop-down lists to select the end date and time in the range you want to search.

  8. Optionally, select the Include deleted meetings in search results option to retrieve information about meetings even if they have been deleted.

  9. Click the Meeting Options to Retrieve tab.

  10. Under Meeting options, click the Data Item field and select the Data Item that you want to hold the value of some meeting option. For example, if you want to store the Meeting ID, you might select a Data Item called "MeetingID".

  11. Click the Return Field field and select the meeting option whose value you want to store. The value set for that meeting option will be stored in the Data Item you selected.

    Note:
    The most common meeting options that you may want to return are Meeting ID (mid), Audience Password (audiencePassword), and Presenter Password (presenterPassword). At the very least, you should save the Meeting ID to a Data Item so you can access this meeting in later activities and send the Meeting ID to attendees.

  12. Select the Clear Existing Values option if you want the Data Item to contain only the value of that meeting option, or unselect that option if you want to add the value of the meeting option to any other values that may already be in the Data Item.

  13. Repeat steps 10 - 11 to store as many meeting values as necessary.

  14. Optionally, select the Save error message, click the Data Item field and select the Data Item that you want to store the error message.
    If Live Meeting returns an when you delete the meeting, this Data Item will store the text of that error message.

  15. Click OK.
    The Properties window closes.


About the Update Live Meeting Activity

You can use the Update Live Meeting activity to change the details of a Live Meeting after the meeting has been created. You can change the people invited to the meeting and any of the meeting options. However, you cannot change information for a meeting that has been deleted.

  • Updating a Live Meeting

Required Auxiliary Topics

Before you begin configuring the Update Live Meeting activity, make sure to complete the following:

  • Create Data Items that will store meeting values and settings.


Updating a Live Meeting

You can use the Update Live Meeting activity to change information about any meeting you have created.

Note:
You can only change information about meetings that were created with the Live Meeting User ID that you select when you set up the Organizer Information. However, if you enter the User ID of an Administrator, you can change information about any meeting.

To update a Live Meeting

  1. Add the Update Live Meeting activity to the Canvas and complete the common activity properties.

  2. Click the Update Live Meeting tab.

  3. Set up the Organizer Information.

  4. Click the Meeting ID and Return Options tab.

  5. Under Meeting to update, choose either Select Data Item or Enter value.

    If you choose Select Data Item, click the drop-down list and select the Data Item that contains the Meeting ID of the Live Meeting you want to update.
    If you choose Enter value, enter the Meeting ID of the Live Meeting you want to update.

  6. Under Meeting attendees and presenters, click the Attendees field and enter the email addresses of the people you want to invite to attend the meeting.

    Note:
    The email address you enter here are not in addition to the original attendees. Instead, they replace the original list. You must enter the email address of every person who should be invited.

    You can also click the Data Items drop-down list and select a Data Item that will contain one or more email addresses or a BPM User ID. Click Add as Attendee to invite those people to attend the meeting. If you selected a Data Item that contains a BPM User ID, BPM Suite will look up the User's email address and use that for the invitation.

    Note:
    Multiple email addresses should be separated with semi-colons.

  7. Click the Presenters field and enter the email addresses of the people you want to invite to present at the meeting.

    Note:
    The email address you enter here are not in addition to the original presenters. Instead, they replace the original list. You must enter the email address of every person who should be invited.

    You can also click the Data Items drop-down list and select a Data Item that will contain one or more email addresses or a BPM User ID. Click Add as Presenter to invite those people to attend the meeting. If you selected a Data Item that contains a BPM User ID, BPM Suite will look up the User's email address and use that for the invitation.

    Note:
    Multiple email addresses should be separated with semi-colons.

  8. Under Meeting options to return, click the Data Item field and select the Data Item that you want to hold the value of some meeting option. For example, if you want to store the Meeting ID, you might select a Data Item called "MeetingID".

  9. Click the Return Field field and select the meeting option whose value you want to store. The value set for that meeting option will be stored in the Data Item you selected.

    Note:
    The most common meeting options that you may want to return are Meeting ID (mid), Audience Password (audiencePassword), and Presenter Password (presenterPassword). At the very least, you should save the Meeting ID to a Data Item so you can access this meeting in later activities and send the Meeting ID to attendees.

  10. Select the Clear Existing Values option if you want the Data Item to contain only the value of that meeting option, or unselect that option if you want to add the value of the meeting option to any other values that may already be in the Data Item.

  11. Repeat steps 8 - 10 to store as many meeting values as necessary.

  12. Click the Options to Update and Remove tab.

  13. Under Meeting options to update, click the Option Name field and select an option that you want to update for this meeting.
    The Type field changes to reflect the type of value required by the option you selected.

  14. Click the Source field and select Value, Display Value, or Constant.

    If you selected Value, the Value field will use the value of the Data Item you select.
    If you selected Display Value, the Value field will use the display value of the Data Item you select.
    If you selected Constant, you will be able to enter the value you want to use at design time.

  15. Click the Value field and enter the value you want to submit for the selected option, or select the Data Item that will contain that value at run time.

  16. Repeat steps 13 - 15 to update as many meeting options as necessary.

  17. Under Meeting options to remove, click the drop-down list and select a meeting option that you want to remove. Removing a meeting option means that it's value will be blank, and it will not be considered when setting up the Live Meeting.

  18. Click OK.
    The Properties window closes.


CAP - Live Meeting Activities

  1. Click the Live Meeting Activities category in the Toolbox.

  2. Double-click the activity you want to add, or drag it to the Canvas.
    The activity is added to the process.

  3. Open the Properties for the activity (double-click the activity or right-click and select Activity Properties).
    The Properties window appears.

  4. Complete the common activity properties.


Setting the Organizer Information

In order to configure any Live Meeting activity, you need to provide a Live Meeting User ID, password, and meeting URL. You can provide this information as constant values that you enter at design time, or you can select Data Items that will hold these values at run time.

  1. Under Organizer User ID, choose either Select Data Item or Enter value.

    If you choose Select Data Item, click the drop-down list and select the Data Item that will contain the Organizer's Live Meeting User ID.
    If you choose Enter value, enter the Organizer's Live Meeting User ID.

    Note:
    If you are using the Retrieve Live Meeting activity, you will only be able to retrieve meetings created by the User ID you enter here. However, if you enter the User ID of an Administrator, you will be able to retrieve any meeting.

  2. Under Organizer Password, choose either Select Data Item or Enter value.

    If you choose Select Data Item, click the drop-down list and select the Data Item that will contain the password for the User ID you selected earlier.
    If you choose Enter value, enter the password for the User ID you selected earlier.

  3. Under Live Meeting URL, choose either Select Data Item or Enter value.

    If you choose Select Data Item, click the drop-down list and select the Data Item that will contain the URL that the participants will use to join the meeting.
    If you choose Enter value, enter the URL that the participants will use to join the meeting.

    Note:
    The URL should always start with https://www.livemeeting.com/cc/

Related Topics

Creating a Live Meeting | Deleting a Live Meeting | Retrieving a Specific Live Meeting | Retrieving All Live Meetings Within a Date Range | Updating a Live Meeting


Additional Options - Manual Activity

For the | Complete the following
Priority | From the Priority drop-down list, select the priority rating you want to give this task or select [Use data item]. If you select [Use data item], select the Data Item that will contain the task's weight value when the process runs. Note: The Priority value gives the user a better understanding for how important this task is in relation to other tasks he or she may have to complete.
Weight | From the Weight drop-down list, select the weight you want to give this task or select [Use data item]. If you selected [Use data item], select the Data Item that will contain the task's weight value when the process runs. Note: Giving the task a specific weight helps BPM Suite determine which user to assign this task to when you do not a specific user.
Help URL | Optional: If you created a help file for this task, enter the URL of the help file. The URL can point to a file on your corporate intranet (\\server\help\help-file.htm) or to a file on the Internet (http://...).
Plug-In | Optional: If you or another member of your organization created a custom plug-in for this task, in the Manual Task Plugin field, enter the name of the Plug-In file. Available Plug-In files are stored in the ManualTaskPlugins folder on the BPM Web server. Note: The Plug-In will override the standard BPM Web manual task plug-in.


Editing the Criteria the System Uses to auto-assign Manual Tasks

Editing the Advanced Options for auto-assigning Standard Manual Tasks

When you create a Standard Manual Task, you can let BPM Suite assign the task to a user. Auto-assigning tasks keeps them distributed evenly among users and assigned to the most readily available user.

When you want BPM Suite to assign the task, it will initially develop a list of users based on Role, Geography, and workload, and then assign the task to the appropriate user. However, you can manipulate the weights for assigning a task automatically.

To edit the Advanced Options for auto-assigning a Standard Manual Task

  1. On the Manual tab of a manual activity, click the Auto assign task based on user class check box.
    The Advanced button becomes available.

    Note:
    You do not have to edit the auto-assignment options. By clicking the Auto-assign task based on user class check box, you tell BPM Suite to auto-assign the task when it's ready to be completed by a user. BPM Suite will use the default options to assign the user.

  2. To edit the auto-assignment options, click the Advanced button.
    The Advanced Options window opens. You can use this window to select the weighted options for making task assignment either process specific, task specific, or account specific.

  3. Check the options you want BPM Suite to take into consideration when determining the assignment. The following table describes your options:

    Process specific options

    Match closest task (in time) for each user within the Current Process Instance

    • This option tells BPM Suite to assign this task to a user within this process that is closest in time with any task.

    Match number of tasks for each user within the Current Process Instance

    • This option tells BPM Suite to assign this task to a user within this process that does not have as many tasks in general as other users.

    Task specific options

    Match closest identical task (in time) for each user within Any Process Instance

    • This option tells BPM Suite to assign this task to a user within any process that is closest in time with an identical task.

      Since this option is based on time among all processes, you should narrow down the number of processes by looking ahead a certain number of days, hours, and minutes.

    Match number of identical tasks for each user within Any Process Instance

    • This option tells BPM Suite to assign this task to a user within any process that does not have as many tasks identical to this task as other users.

      Since this option is based on time among all processes, you should narrow down the number of processes by looking ahead a certain number of days, hours, and minutes.

    Account specific options

    Match closest task (in time) for each users within Any Process Instance by Account ID

    • This option tells BPM Suite to assign this task to a user within any process that is closest in time with the same Account ID as this task.

      Since this option is based on time among all processes, you should narrow down the number of processes by looking ahead a certain number of days, hours, and minutes.

    Match number of tasks for each user within Any Process Instance by Account ID

    • This option tells BPM Suite to assign this task to a user within any process that does not have as many tasks with the same Account ID as this task.

      Since this option is based on time among all processes, you should narrow down the number of processes by looking ahead a certain number of days, hours, and minutes.

  4. If you want BPM Suite to take a user's workload into consideration, click Use Workload.

  5. If you clicked Use Workload, click either the Independently option or the As a Weighted option to determine how BPM Suite will use a person's workload when assigning the task.

  6. Click OK.
    The Advanced Options window closes.

Related topics

Understanding BPM Activities |


Manual Extended - BPM Web Task Name

Setting the Name of the Task in BPM Web

A manual activity creates a task for one ore more workers. One common way to complete tasks is through BPM Web. When user's complete tasks in BPM Web, it is important that they can tell what a task is by its name. You can use BPM Designer to define the task name through one of three methods.

Setting the Task Name From the Activity Name

By default, tasks in BPM Web have the same name as the manual activity that created them.

  1. Open the properties of the manual activity.

  2. Click the Extended Properties tab.
    The Task Plug-in and WSDL sub-tab is in front.

  3. Select Use activity name.

The task in BPM Web will now have the same name as the manual activity in BPM Designer.

Setting the Task Name From a Data Item

You can use the contents of a Data Item as the name of a task in BPM Web.

  1. Open the properties of the manual activity.

  2. Click the Extended Properties tab.
    The Task Plug-in and WSDL sub-tab is in front.

  3. Select the Select Data Item option.

  4. Click the drop-down list and select the Data Item that contains the name you want to give the task in BPM Web.

The task in BPM Web will now use the contents of the Data Item as the name of the task.

Setting the Task Name Manually

If you want to enter a custom task name that will be used every time the manual activity creates a task, you can enter it manually.

  1. Open the properties of the manual activity.

  2. Click the Extended Properties tab.
    The Task Plug-in and WSDL sub-tab is in front.

  3. Select the Task Name option.

  4. Click in the box next to Task Name and enter the name you want to give the task in BPM Web.

The task in BPM Web will now use the manually entered text as the name of the task.

Related topics

Generating an InfoPath Form, Generating an ASP.NET Web Form, Generating the WSDL


Manual Extended - Data Item Access

Defining a User's Access to Data Items

You can determine which Data Items are visible to your users. This is useful in situations where you have many data items, but you only want users to see some of them.

  1. Add a Manual Activity to the designer.

  2. Double-click the activity's icon.
    The Properties window opens.

  3. Click the Extended Properties tab.

  4. Click the Data Item Display sub-tab.
    Click the arrow buttons to add or remove Data Items from the list of Visible Data Items.

    5. Button | Function
 | Adds the selected Data Item to the list of Visible Data Items
 | Adds all Data Items to the list of Visible Data Items
 | Removes the selected Data Item from the list of Visible Data Items
 | Removes all Data Items from the list of Visible Data Items

    Note
    You can also double-click a Data Item in the Available Data Items list to move that Data Item to the end of the list.


Manual Extended - Data Item Appearance and Behavior

Defining a Data Item's Appearance and Behavior

You make Data Items required or optional, change the order in which they appear, and determine a user's read/write access.

  1. Add a Manual Activity to the designer.

  2. Double-click the activity's icon.
    The Properties window opens.

  3. Click the Extended Properties tab.

  4. Click the Data Item Display sub-tab.
    The toolbar over the right-hand pane gives you control over several aspects of your Data Items.

Button | Function
 | Makes the Data Item Read Only
 | Makes the Data Item Readable and Writable
 | Makes the Data Item Required
 | Makes the Data Item Optional
 | Moves the Data Item up in the display order
 | Moves the Data Item down in the display order


Manual Extended - Data Item Display

Data Item Display tab

Using the Data Item Display tab, you can set the visibility for Data Items associated with the task, and determine whether the item should be required, and whether the item should be enabled.

Note:
If you do not see any Data Items when you click the Data Item Display tab, click the Show Visible Data Items Only check box to remove the check mark. All Data Items associated with the current process appear.

Required
To make the selected Data Item required, click the check mark icon. To make the selected Data Item not required, click the cancel icon.

Read-Only
To make the selected Data Item read-only, click the locked lock icon. To make the item modifiable, click the unlocked lock icon.


Manual Extended - Data Item Validation

Data Item Validation tab

Using the Data Item Validation tab, you can create validation rules to check if a user completed Data Items correctly.

  • In the Expression column, click the ellipses button to access the Data Item Validation window. Using this window, you can construct an expression to test Data Item values

  • In the Return Message if True column, enter the message for the user to see when the Data Item's information is entered correctly.

  • In the Return Message if False column, enter the message for the user to see when the Data Item's information is entered incorrect.


Manual Extended - Generating an ASP.NET Web Form

Generating an ASP.NET Plug-In

You can create a modifiable ASP.NET web form through this plug-in that can be used to complete a manual task.

Generating the ASP.NET Plug-In

  1. Open the properties of the manual activity.

  2. Click the Extended Properties tab.
    The Task Plug-in and WSDL sub-tab is in front.

  3. Click the Generate ASP.NET Plug-In button.
    The ASP.NET Plug-In Generation screen will appear.

  4. Enter the a name for the form into the Page title text box.

  5. Select Open the form for editing if you wish to open and edit the form immediately.

  6. Select Use the ASP.NET plug-in if you wish to set the plug-in for this activity to the ASP.NET plug-in you are creating.
    Note:
    This option is selected by default.

  7. Click OK.
    You Save As dialog will appear.

  8. Browse to the location in which you wish to save the form.

  9. Click Save.
    The ASP.NET Plug-In Generation dialog will close; an ASP.NET web form will be generated; for each Data Item listed in the Data Item Display tap, an input control will be added to web form.

    Note:
    You must deploy the form before users can access it. Please see the Deploying Manual Task Plug-ins section in the Operations Guide for deployment instructions.


Manual Extended - Generating an InfoPath Form

Generating an InfoPath Form

You can create a modifiable InfoPath form through this plug-in that can be used to complete a manual task.

Generating the InfoPath Form

  1. Open the properties of the manual activity.

  2. Click the Extended Properties tab.
    The Task Plug-in and WSDL sub-tab is in front.

  3. Click the Generate InfoPath 2007 Form button.
    The InfoPath 2007 Form Generation dialog will appear.

  4. Enter the a name for the form into the Form name text box.

  5. Select Open the form for editing [InfoPath client required] if you wish to open and edit the form immediately.

  6. Select the compatibility you wish the form to have from the InfoPath version compatibility group box.

    • Select Create an InfoPath client and Form services compatible form if you are using SharePoint Form Services; the form will still be compatible with the InfoPath client.

    • Select Create an InfoPath client only compatible form if you are not using SharePoint Form Services; form users must have the InfoPath client installed to oepn and fill out the form

  7. Click OK.
    The Save As dialog will appear.

  8. Select the location in which you wish to save the form.

  9. Click Save.
    An InfoPath form will be generated in the location selected; for each Data Item listed in the Data Item Display tab, an input control will be added to the InfoPath form.

    Note:
    You must deploy the form before users can access it. Please see the Deploying Manual Task Plug-ins section in the Operations Guide for deployment instructions.


Manual Extended - Manual Task Plugin

Selecting a Manual Task Plug-In

BPM Suite comes with two plug-ins that come with BPM Suite to display a task for a user.

Default.aspx

This plug-in provides a table of every Data Item made available in the manual activity. Unless the Data Item has been designated as "Read Only" (General Properties, Extended Properties, Data Item Display), each Data Item is paired with a field that can accept a value. If it is Read Only, the value is displayed but is not editable. The type of field depends on the Data Type of the Data Item.

DocView.aspx

This plug-in divides the task window into two panes. The left pane provides the same table of Data Items made available in the manual activity. The right pane provides a tab for each Hyperlink Data Item or FilePointer Data Item in the manual activity. If the Data Item is a FilePointer, the user can click a tab to view the associated file. For example, if you included a FilePointer Data Item that contains a PDF, then that PDF would be visible in the task window (if the user's browser has a plug-in that enables him to view PDFs). The tab view in the right pane can display any file, as long as the user's browser is capable of displaying it. If a FilePointer Data Item is not already associated with a file, then an "Upload New" button appears in the tab, and the user can select a file to put in the FilePointer Data Item. If the Data Item is a Hyperlink, the Web page reference in the hyperlink will be displayed inside the tab.

Other Plug-Ins

You, or someone in your organization, may have created a manual task plug-in that you need to use with certain manual activities in your processes. A manual task plug-in uses a custom user interface for the manual task completion window. In order to use the manual task plug-in, you will need to refer to the form within the properties of your manual activities.

Depending on which type of plug-in you have created, you will have to move it to the location where BPM Web or SharePoint Web Parts are installed. For BPM Web plug-ins, copy the file to the ManualTasksPlugin directory located at
C:\Program Files\Bluespring\bpm web\[site] (where C:\ is the letter of the file of your hard drive). For SharePoint plug-ins, copy the file to the root SharePoint Web directory located at C:\Program Files\Bluespring\bpm SharePoint\web (where C:\ is the letter of your hard drive).

To read more information about creating manual task plug-ins or to download sample plug-ins, visit the Bluespring Solution Center.

  1. Add a Manual Activity to the Canvas and complete the standard properties.

  2. Open the Properties for the activity (double-click the activity or right-click and select Activity Properties).
    The Properties window appears.

  3. Click the tab that relates to that specific manual activity (e.g., Manual, User Type, Multiple Assignment).

    Note:
    If you are using the Group Assign activity, you also need to click the Duration/Escalation subtab.

  4. Under Additional Options, click the Ellipsis button to the right of the Plug-In box.
    The Select plug-in window appears.

  5. Select the manual task plug-in using one of the following methods:

    • Use the default plug-in (Default.aspx) by clicking the Use default BPM Web task form option.

    • Use a built-in plug-in by clicking the Use plug-in option, clicking the down arrow, and then clicking a plug-in. First, you must add the plug-in file name to the Sys_ManualTaskPlugins lookup list for the plug-in to be available. To do this, click the Configuration Management tab, click Manage Lists, then double-click the Sys_ManualTaskPlugins table name.

    • Use a custom plug-in by clicking Use custom URL, and then typing the Web address in the URL box. You can use the Data Items drop-down list to select Data Items from the activity and insert their display values or values using the Insert Display Value and Insert Value button respectively.

Note:
Be sure to include the .aspx file extension.

  6. Click OK.
    The Select plug-in window closes and the Property tab appears.

  7. Click OK.
    The Properties window closes.

  8. Save the process.

The chosen plug-in will be used the next time the process runs and a user opens the manual task in BPM Web.


Manual Extended - User Assignment Persistence

Saving a User Assignment to Use Again Later

If you assign a user to an activity, and you want to make sure that user is assigned to a related activity later, you can save the user assignment in a data item.

  1. Add a Manual Activity to the designer.

  2. Double-click the activity's icon.
    The Properties window opens.

  3. Click the Extended Properties tab.

  4. Click the User Assignment Persistence sub-tab.

  5. Click the check box labeled Save the User Assignment for this Manual Task to a Data Item.
    The Data Items list becomes activated.

  6. Select a Data Item from the Available Data Items list if you want to save the user assignment to an existing Data Item. Click the Add Data Item button if you want to save the user assignment to a new Data Item.

  7. Click OK.

Now that the user assignment is saved in a Data Item, you can use the Data Item to assign that user to a related activity later. This is frequently accomplished with the Prior Manual Activity tool.


Manual Extended - Validation Rules

Creating Validation Rules for Data Items

You can create rules that define what sort of data can be accepted into a Data Item.

  1. Add a Manual Activity to the designer.

  2. Double-click the activity's icon.
    The Properties window opens.

  3. Click the Extended Properties tab.

  4. Click the Data Item Validation sub-tab.

  5. Click in the first row of the Expression column. An ellipsis button ( [image]) appears.

  6. Click the ellipsis button. The Data Item Validation window appears.

  7. Click the drop-down list labeled Available Data Items and select a Data Item. The Data Item (either its value or display value, depending on which option you have selected) appears in the box below the drop-down menu.

  8. Use the basic math and logical expressions provided to create a rule for the Data Item.

    Example:
    %SelectedDataItem.Value% > 2
    Which specifies that the Data Item's value must be greater than 2.

  9. Click in the Populate Variables to Test Expression field and enter a possible value for the Data Item.

  10. Click the Test Expression button. The Expression Results field displays the result.

  11. Click OK when you are satisfied with the validation rule. You will see the Data Item Validation sub-tab again.

  12. Click in the first row of the Return Message if True column. You are now able to enter a message that will be displayed to users who enter a value for the Data Item that returns true.

  13. Click in the first row of the Return Message if False column. You are now able to enter a message that will be displayed to users who enter a value for the Data Item that returns false.

    Example:
    Your message may say something like, "You must enter a value greater than 2. Please try again."


Manual Extended - WSDL

Generating the Web Service Description Language (WSDL)

Every process in BPM Suite has a Web Services Description Language (WSDL) file that describes the process. You can use the WSDL file to start and manipulate (to some extent) a process. The most common use for WSDL files is to start a process through some third-party interface, such as Microsoft InfoPath or a Web form.

Generating the WSDL

  1. Open the properties of the manual activity.

  2. Click the Extended Properties tab.
    The Task Plug-in and WSDL sub-tab is in front.

  3. Click the Generate WSDL button.
    The WSDL location will now be displayed in the WSDL text box.

Accessing the WSDL

  1. Click the Copy to Clipboard button.

  2. Open a browser window.

  3. Paste the WSDL location into the address bar.
    The WSDL file will be displayed

Related Topics
Viewing the Process Initiation URL


About the Dynamic Role Assignment Activity

You can use the Dynamic Role Assignment activity to assign a task to a given Role. What makes this activity different from the Standard Manual Activity is that the Role must be provided by a Data Item. This means the Role is determined during the course of the process, not when you configure the activity. Similarly, when the task escalates, it will escalate to a Role that is defined by a Data Item.

The Data Item that provides Role needs to contain the name of the Role as text. The text is not case-sensitive.

In all other ways, the Dynamic Role Assignment activity is like the Standard Manual Activity.

Important Note

In order for a manual activity to make use of the business calendar, a User's profile must include a value for State and Zip Code. State and Zip Code are not required values for all User profiles, so you should use Access Management to ensure the profiles include this information.

Dynamically Assigning a Task to a Role

  • Dynamically Assigning a Task to a Role

  • Dynamically Assigning a Task to a User in a Role

Notification, Escalation, and Time Options

You should complete the following options for each manual activity before you start a process:

  • Configuring Notification Options

  • Escalation Options for Dynamic Role Assignments

  • Time Options for Manual Activities

Other Options

The Standard Manual activity allows you to set several other options that apply to the task they create.

  • Setting Geographies for the Dynamic Role Assignment Activity

  • Selecting a Manual Task Plugin

  • Setting the Name of the Task in BPM Web

Extended Properties

The Extended Properties tab provides additional features that let you control Manual Activities in more detail.

  • Completing the Extended Properties tab for Manual Tasks

Related Topics

About the Standard Manual Activity | About the Prior Manual Activity | About the Group Assign Activity | About the User Type Assignment Activity


Dynamically Assigning a Task to a Role

You can use the Dynamic Role Assignment activity to assign work to a Role. The Role must be provided as text in a Data Item. If you already know which specific Role you want to complete a task, then you can use the Standard Manual Activity to assign the task. This activity is intended for situations where you want to assign a task to a Role, but you do not want to decide which Role until after the process starts.

When you assign a task to a Role, the task is placed in an unassigned task pool for that Role. Any user in the Role can view and complete the task. If you want the task to be assigned to a specific person within the Role, refer to the article on dynamically assigning a task to a User in a Role.

Note

In order for this activity to work properly, you need to create a step in your process that populates a UserID Data Item with a User's ID number. You can also use User Assignment Persistence to put a User's information in a Data Item.

To Dynamically Assign a Task to a Role

  1. Add the Dynamic Role Assignment activity to the Canvas and complete the common activity properties.

    Note:
    Completing common activity properties is essential to create an organized and functional process.

  2. Click the Dynamic tab.

  3. Click the field in the Role row.
    A list of UserID Data Items appears.

  4. Select the UserID Data Item that contains the name of the Role to which you want to assign this task.

  5. Optionally, set the notification options.

  6. Optionally, set the geography options.

  7. Set the Time Options.

    Note:
    Setting the time options allows you to control when a task will escalate or time out.

  8. If you want the task to escalate, set the Escalation Options.

  9. Optionally, configure the Additional Options.

  10. Complete the Extended Properties tab.

  11. Click OK.
    The Properties window closes.


Dynamically Assigning a Task to a User in a Role

Ordinarily, when you use the Dynamic Role Assignment activity, it creates a task in the unassigned task pool for the activity. This means any User in the Role can view and accept the task. However, if you want BPM Suite to automatically assign the task to a specific User in the Role, then you can configure the activity to do so.

Note

In order for this activity to work properly, you need to create a step in your process that populates a UserID Data Item with a User's ID number. You can also use User Assignment Persistence to put a User's information in a Data Item.

To Dynamically Assign a Task to a User in a Role

  1. Add the Dynamic Role Assignment activity to the Canvas and complete the common activity properties.

    Note:
    Completing common activity properties is essential to create an organized and functional process.

  2. Click the Dynamic tab.

  3. Click the field in the Role row.
    A list of UserID Data Items appears.

  4. Select the UserID Data Item that contains the name of the Role to which you want to assign this task.

  5. Select the Auto-assign task based on Role option in the Manual Task Settings section.

  6. Optionally, set the notification options.

  7. Optionally, set the geography options.

  8. Set the Time Options.

    Note:
    Setting the time options allows you to control when a task will escalate or time out.

  9. If you want the task to escalate, set the Escalation Options.

  10. Optionally, configure the Additional Options.

  11. Complete the Extended Properties tab.

  12. Click OK.
    The Properties window closes.


Escalation Options for Dynamic Role Assignments

When a Dynamic Role Assignment activity escalates, it can only escalate to another Role. You can select Data Items that will contain the names of the Roles to which you want to escalate, up to three escalations.

To Set Escalation Options for Dynamic Role Assignments

  1. If you have not done so already, configure the activity using one of the following methods:

    • Dynamically Assigning a Task to a Role

    • Dynamically Assigning a Task to a User in a Role

  2. Optionally, set the notification options.

  3. Optionally, set the geography options.

  4. Set the Time Options so that the task escalates after some period of time.

    Note
    Depending on how you set the time options, the task may timeout instead of escalate.

    Note
    The task will not escalate if the time options are set to 0 day, 0 hours, and 0 minutes. You must select a time longer than 0 minutes to enable escalation.

  5. Set the Escalation Interval by changing the Days, Hours, and Minutes counters. The escalation interval determines how long the activity will wait before it moves from the first escalation to the second and from the second to the third.

  6. Optionally, select the Timeout after escalations option if you want the activity to timeout if the last escalation is not performed in time. If the activity does not timeout, then it will fail.

  7. Click the field next to the Role field under Escalation User 1 Information and select the Data Item that will contain the name of the Role to which you want to escalate this task.

  8. Optionally, repeat step 7 for the Escalation User 2 Information and Escalation User 3 Information sections.

  9. Optionally, configure the Additional Options.

  10. Complete the Extended Properties tab.

  11. Click OK.
    The Properties window closes.


Setting a Geography for a Dynamic Role Assignment

If you use the Dynamic Role Assignment activity to dynamically assign a task to a Role or to a User in a Role, then you can also specify a geography where the User who receives the task must be a member.

To Set a Geography for a Dynamic Role Assignment

  1. If you have not already done so, configure the activity using one of the following methods:

    • Dynamically Assigning a Task to a Role

    • Dynamically Assigning a Task to a User in a Role

  2. Optionally, set the notification options.

  3. Click the Geography button.

  4. Select the Consider Geography when assigning this task option.
    The options in the group box become enabled.

  5. Choose either Select or Use Data Item for the Geography Set option.
    If you choose Select, use the drop-down list to select a Geography Set now.
    If you choose Use Data Item, use the drop-down list to select the Data Item that will contain the name of a Geography Set at run time.

  6. Choose either Select or Use Data Item for the Geography option.
    If you choose Select, use the drop-down list to select a Geography. If you chose Use Data Item earlier for the Geography Set, you will not be able to select a Geography in this window. If you define the Geography Set at run time, you must also define the Geography at run time.
    If you choose Use Data Item, you can use the drop-down list to select the Data Item that will contain the name of a Geography at run time.

  7. Click OK.


About the Group Assign Activity

You can use the Group Assign activity to assign the same task to multiple Users. You can configure the activity so that some Users must complete the task, some are optional, and some only receive notification of the task.

Important Note

In order for a manual activity to make use of the business calendar, a User's profile must include a value for State and Zip Code. These are not required values for all User profiles, so you should use Access Management to ensure the profiles include this information.

Below is a list of possible configurations that you can use with Group Assign activity:

  • Assigning a Task to a Role or part of a Role

  • Setting a Geography for Role assignments in Group Assign

  • Assigning a Task to a Hand-Picked Selection of Users

  • Defining Completion Settings

Notification, Escalation, and Time Options

Because the Group Assign activity can apply to large groups of diverse users, you have more options when setting time, escalation, and notification options than you do with other manual activities.

  • Setting Time, Escalation, and Notification Options

Other Options

The Standard Manual activity allows you to set other options that apply to the task they create.

  • Selecting a Manual Task Plugin

  • Setting the Name of the Task in BPM Web

Required Auxiliary Topics

Complete the Extended Properties tab to define what task the Users much complete and other options.

  • Completing the Extended Properties tab for Manual Tasks

Related Topics

About the Standard Manual Activity | About the Prior Manual Activity | About the User Type Assignment Activity | About the Dynamic Role Assignment Activity


Assigning a Task to a Hand-Picked Selection of Users

You can use the Group Assign activity to assign a task to a hand-picked selection of Users from different Roles.

To assign a task to a hand-picked selection of Users

  1. Add the Group Assign activity to the Canvas and complete the common activity properties.

    Note:
    Completing the common activity properties is essential to creating an organized and functional process.

  2. Click the Multiple Assignment tab. The 1. Role Assignment sub-tab is in front.

  3. Click the 2. User Assignment sub-tab. A grid that contains the name of every User in the BPM system appears.

  4. Select the Task User checkbox next to the Users you want to task.

    Note:
    You can also select the Allow Add User checkbox to give a User the ability to add another User to the task through the Web interface.

  5. Continue to the 3. Completion Settings sub-tab to define when the activity will be marked as complete.

Related Topics

Assigning a Task to a Role or a Part of a Role | Defining Completion Settings for a Group Assign Activity.


Assigning a Task to a Role or Part of a Role

Assigning a Task to a Role or a Part of a Role

You can use the Group Assign activity to assign a task to every member of a Role or to a part of that Role.

This option is different than assigning a task to a Role. When you use a Standard Manual activity to assign a task to a Role, the task goes to an unassigned task pool, where any User in that Role can complete the task. In contrast, when you use the Group Assign activity, you assign the task to every member of the Role.

To assign a task to a every member of a Role

  1. Add the Group Assign activity to the Canvas and complete the common activity properties.

    Note:
    Completing the common activity properties is essential to creating an organized and functional process.

  2. Click the Multiple Assignment tab. The 1. Role Assignment sub-tab is in front. The top pane shows a list of Roles and the lower pane shows a list of Users in each Role.

  3. Select the Task Role checkbox next to the Role(s) you want to task. Click any other row in the top pane to cause the lower pane to reflect your selection in the top pane.

    Note:
    You can also select the Task New Users checkbox to ensure that Users who you add to the Role will also be tasked the next time the process is run.

  4. Select or de-select the Task User checkbox next to Users in the lower pane if you want to assign the task to only a part of a Role.

    Note:
    You can also select the Allow Add User checkbox to give a User the ability to add another User to the task through the Web interface.

  5. Continue to the 3. Completion Settings sub-tab to define when the activity will be marked as complete.

Related Topics

Assigning a Task to a Hand-Picked Selection of Users | Defining Completion Settings for a Group Assign Activity.


Defining Completion Settings for a Group Assign Activity

Defining Completion Settings

You can configure a Group Assign activity so that some Users must complete the task, some are optional, and some only receive notification of the task.

To configure completion settings

  1. Add the Group Assign activity to the Canvas and complete the common activity properties.

    Note:
    Completing the common activity properties is essential to creating an organized and functional process.

  2. Click the Multiple Assignment tab. The 1. Role Assignment sub-tab is in front.

  3. Click the 3. Completion Settings tab. The upper section lets you determine how many Users must complete the task for BPM to mark the activity as Completed. The lower section lets you define which users are required to complete the task, which are optional, and which Users only receive a notification of the task.

  4. Select Use Percentage to mark the activity as Completed when a percentage of Users complete the task, or select Use Number to mark the task as complete when a certain number of Users complete the task.

    Note:
    You can click the drop-down list and select a number now, or you can select a Data Item that will contain the number at run-time.

  5. Select a User in the lower section of the window. The User may be required to complete the task, optionally complete the task, or only receive a notification of the task.

    Note:
    By default, all users are set to optionally complete the task.

  6. Click the buttons at the upper-left of the pane to change the settings for the selected User. Click the buttons at the upper-right of the pane to change the settings for every User.

    Note:
    Required and optional Users count toward the number of Users required to mark the activity as Completed. Users set to Notify Only do not count toward the number of required Users.

  7. Continue to the 4. Duration/Escalation sub-tab to set time, escalation, and notification options.

Related Topics

Assigning a Task to a Hand-Picked Selection of Users | Defining Completion Settings for a Group Assign Activity.


Setting a Geography for Role Assignments in the Group Assign Activity

When you assign a task to a Role in the Group Assign activity, you can also limit that assignment to the Users who are within a certain Geography. For example, if you want to assign a task to all Sales team members in New York, you could select the Sales Role, then choose the New York geography.

To set a geography

  1. Click the Multiple Assignment tab.
    The 1. Role Assignment sub-tab is in front.

  2. Assign the task to a Role by selecting the Task Role option.
    The Geography column becomes enabled.

  3. Click in the Geography column for the selected Role.
    An ellipsis button appears.

  4. Click the ellipsis button.
    The Geography Settings for [selected] Role window appears.

  5. Select the Consider Geography when assigning this task option.
    The options in the group box become enabled.

  6. Choose either Select or Use Data Item for the Geography Set option.
    If you choose Select, use the drop-down list to select a Geography Set now.
    If you choose Use Data Item, use the drop-down list to select the Data Item that will contain the name of a Geography Set at run time.

  7. Choose either Select or Use Data Item for the Geography option.
    If you choose Select, use the drop-down list to select a Geography now. However, if you chose Use Data Item earlier for the Geography Set, you will not be able to select a Geography in this window. If you define the Geography Set at run time, you must also define the Geography at run time.
    If you choose Use Data Item, use the drop-down list to select the Data Item that will contain the name of a Geography at run time.

  8. Click OK.


Setting Time, Escalation, and Notification Options

You can configure a Group Assign activity so that it times out or escalates to another User after a certain time. You can also set notification options for all three types of Users in the Group Assign activity.

To set time and escalation options

Time and escalations options for the Group Assign activity are very similar to the other Manual activities; however, you must click the 4. Duration/Escalation sub-tab to see them.

  • Time Options for Manual Activities

  • Escalation Options for Manual Activities

To set notification options

You have more notification options for the Group Assign activity than for other Manual activities because you will probably want to send a different notification message to Users who are required, optional, and notify only. For that reason, the Notification Options are the same as every other Manual activity, except you can see different options for all three kinds of Users.

  • Time Options for Manual Activities

Related Topics

About the Group Assign Activity.


About Prior Manual Activities

About the Prior Manual Activity

Use a Prior Manual activity when a user cannot complete the current task you want to assign unless he/she participated in another manual activity. The Prior Manual activity allows you to assign a task to user based upon whether he/she completed or was assigned a manual activity in the current, or a different, process.

Important Note

In order for a manual activity to make use of the business calendar, a User's profile must include a value for State and Zip Code. These are not required values for all User profiles, so you should use Access Management to ensure the profiles include this information.

Below is a list of the task assignment methods that you can complete using a Prior Manual activity:

  • Assigning a Task to a User Assigned a Prior Task in the Current Process

  • Assigning a Task to a User who Completed a Prior Task in the Current Process

  • Assigning a Task to a User Assigned a Task in Another Process

  • Assigning a Task to a User who Completed a Task in a Different Process

If you want any released tasks to enter the unassigned task pool in BPM Web according to the Role of the User assigned to the task, then you should allow user's roles to define a Prior Manual activity's role.

  • Allowing a User's Role to Define a Prior Manual Activity's Role

Other Options

The Standard Manual activity allows you to set other options that apply to the task they create.

  • Selecting a Manual Task Plugin

  • Setting the Name of the Task in BPM Web

Required Auxiliary Topics

If you are assigning a task to a user based on his/her participation in another process, then you need to create a Data Item that holds the User ID of the user.

  • Creating a User ID Data Item

Assigning a prior manual tasks may requires information from other tasks in the process, which you can automatically transfer by linking the prior manual task to previous activities in the process.

  • Linking Activities within Processes

An essential part of assigning prior manual activities is successfully completing the extended properties tab.

  • Completing the Extended Properties tab for Manual Tasks

Furthermore, you should complete the following options for each manual activity before you initiate a process.

  • Configuring Notification Options

  • Escalation Options for Manual Activities

  • Time Options for Manual Activities

Related Topics

About the Standard Manual Activity | About the User Type Assignment Activity | About the Group Assign Activity | About the Dynamic Role Assignment Activity


Allowing a User's Role to Define a Prior Manual Task's Role

Assigning a Prior Manual Activity's Role Based on the User's Role

When you configure a Prior Manual activity, you can set a Default Role, which is a Role that will receive the task if the assigned User releases it. However, you might not be able to choose the correct Default Role at design time. In that case, you can set the Default Role to be the same as the Role of the User who receives the task originally.

To assign a Prior Manual Activity's Role based on the User's Role

  1. Add the Prior Manual Activity to the Canvas and complete the common activity properties.

    Note:
    Completing common activity properties is essential to create an organized and functional process.

  2. Click the Manual tab.

  3. Complete one of the following choices:

    • Assign a Task to a User Assigned a Prior Task in the Current Process

    • Assign a Task to a User Assigned a Task in a Different Process

    • Assign a Task to a User who Completed a Prior Task in the Current Process

    • Assign a Task to a User who Completed a Task in a Different Process

  4. Click the Default Role drop-down list and select a Default Role to the task.

    Note:
    When you assign a Default Role, you ensure that only a User with that Role can complete the task.

  5. Click the Inherit Role checkbox.
    At run time, the Default Role will be replaced by the Role of the User assigned to the activity.

  6. Set the Time Options.

    Note:
    Setting the time options allows you to control when a task will escalate or time out.

  7. If you want the task to escalate, set the Escalation Options.

  8. Optional: Configure the Notification Options .

  9. Complete the Extended Properties tab.

  10. Click OK to close the Properties window.

If a User assigned to the task releases it, the task will enter a role-specific unassigned task pool that matches the Role of the User assigned to the task.


Assigning a Task to a User Assigned a Prior Task in the Current Process

It is common for a user to have more than one task assignment in the same process because a user may have skills/knowledge that are required to complete a certain manual task type that occurs throughout it.

If you want to assign a similar task type in the current process to the same user, use the Prior Manual activity to assign a task to a user based on his/her prior assignments in the current process.

To assign a task to a user assigned a prior task in the current process

  1. Add the Prior Manual activity to the designer canvas and complete the common activity properties.

    Note:
    Completing common activity properties is essential to create an organized and functional process.

  2. Click the Manual tab.

  3. Using the Assignment Method drop-down list, select Relative to Prior Task in Current Workflow.
    A Pick Task drop-down list appears under the Assignment Method drop-down list .

  4. Using the Pick Task drop-down list, select the prior task that you want to base your current activity assignment on.
    The name of the task you picked appears in the list field.

    Note:
    You will only be able to select a manual task that is linked previously in the process, since these tasks are the only ones completed by users.

  5. Click the Original Assignee radio button.

  6. Using the Default Role drop-down list, select a default role to assign to the task.

    Note:
    When you assign a default role, you ensure that if the user releases the task, it will enter the default role's unassigned task pool in BPM Web.

  7. Set the Time Options.

    Note:
    Setting the time options allows you to control when a task will escalate or time out.

  8. If you want the task to escalate, set the Escalation Options.

  9. Optional: Configure the Notification Options .

  10. Complete the Extended Properties tab.

  11. Click OK.
    The Properties for Activity window closes.

When the activity executes, it will assign the task to the user who was assigned the previous task that you selected from the current process.


Assigning a Task to a User Assigned a Task in Another Process

It is common for a user to have more than one task assignment across different processes because he/she may have skills/knowledge that are required to complete a certain manual task type.

In this instance, you may want to ensure that the same user is assigned to the same manual task type, regardless of what process he/she participated in.

To achieve this assignment type, configure a Prior Manual activity to use a data item to assign a user a task based on his/her assignment in another process.

To assign a task to a user assigned a task in another process

  1. Add the Prior Manual Activity to the designer canvas and complete the common activity properties.

    Note:
    Completing common activity properties is essential to create an organized and functional process.

  2. Click the Manual tab.

  3. Using the Assignment Method drop-down list select Use a Data Item.
    A Pick Data Item drop-down list appears under the Assignment Method drop-down list .

  4. Using the Pick Data Item drop-down list, select the data item that stores the User ID and original assignee of the task from a different process that you want to base your current assignment on.
    The name of the data item you picked appears in the drop-down list field.

    Note:
    You should only select a Data Item that originates from a task that used User Assignment Persistence in the extended properties tab. This action ensures that the Data Item stores both the User ID and Assignee information.

  5. Click the Original Assignee radio button.

  6. Using the Default Role drop-down list, select a default role to assign to the task.

    Note:
    When you assign a default role, you ensure that if the user releases the task, it will enter the default role's unassigned task pool in BPM Web.

  7. Set the Time Options.

    Note:
    Setting the time options allows you to control when a task will escalate or time out.

  8. If you want the task to escalate, set the Escalation Options.

  9. Optional: Configure the Notification Options and Additional Options.

  10. Complete the Extended Properties tab.

  11. Click OK.
    The Properties for Activity window closes.

When the activity executes, it will assign the task to the user corresponds to the User ID Data Item that you selected above.


Assigning a Task to a User who Completed a Prior Task in the Current Process

Assigning a Task to a User that Completed a Prior Task in the Current Process

BPM Suite allows users to release, escalate, or time out a task if they are unable to complete it. When this event occurs, the task may be assigned to another user.

As a result, sometimes a user -- who was not originally assigned a task -- completes it. This event may be a problem if the current task you are designing requires knowledge gained from a previous task in order for a user to complete it.

In this instance, you can ensure that the right user is assigned the task by using the Prior Manual activity to assign a task to a user that completed a prior task in the current process.

To assign a task to a user that completed a prior task in the current process

  1. Add the Prior Manual Activity to the designer canvas and complete the common activity properties.

    Note:
    Completing common activity properties is essential to create an organized and functional process.

  2. Click the Manual tab.

  3. Using the Assignment Method drop-down list, select Relative to Prior Task in Current Workflow.
    A Pick Task drop-down list appears under the Assignment Method drop-down list.

  4. Using the Pick Task drop-down list, select the prior task that you want to base your current task assignment on.
    The name of the task you picked appears in the list field.

    Note:
    You will only be able to select a manual task that is linked previously in the process, since these tasks are the only ones completed by users.

  5. Click the Final Executer radio button.

  6. Using the Default Role drop-down list, select a default role to assign to the task.

    Note:
    When you assign a default role, you ensure that if the user releases the task, it will enter the default role's unassigned task pool in BPM Web.

  7. Set the Time Options.

    Note:
    Setting the time options allows you to control when a task will escalate or time out.

  8. If you want the task to escalate, set the Escalation Options.

  9. Optional: Configure the Notification Options .

  10. Complete the Extended Properties tab.

  11. Click OK.
    The Properties for Activity window closes.

When the activity executes, it will assign the task to the user that actually completed the task you to which you linked this activity.


Assigning a Task to a User who Completed a Task in a Different Process

Assigning a Task to a User who Completed a Task in Another Process

If you want to ensure that you assign a task to a user that has completed similar tasks in a different process, configure a prior manual activity to use a data item to assign the activity.

To assign a task to a user that completed a task in another process

  1. Add the Prior Manual Activity to the designer canvas and complete the common activity properties.

    Note:
    Completing common activity properties is essential to create an organized and functional process.

  2. Click the Manual tab.

  3. Using the Assignment Method drop-down list, select Use a Data Item.
    A Pick Data Item drop-down list appears under the Assignment Method drop-down list .

  4. Using the Pick Data Item drop-down list, select the data item that stores the User ID and final executor of the task from a different process that you want to base your current assignment on.
    The name of the data item you picked appears in the list field.

    Note:
    You should only select a data item that originates from a task that used User Assignment Persistence in the extended properties tab.

  5. Click the Final Executer radio button.

  6. Using the Default Role drop-down list, select a default role to assign to the task.

    Note:
    When you assign a default role, you ensure that if the user releases the task, it will enter the default role's unassigned task pool in BPM Web.

  7. Set the Time Options.

    Note:
    Setting the time options allows you to control when a task will escalate or time out.

  8. If you want the task to escalate, set the Escalation Options.

  9. Optional: Configure the Notification Options .

  10. Complete the Extended Properties tab.

  11. Click OK.
    The Properties for Activity window closes.

When the activity executes, it will assign the task to the user that corresponds to the User ID Data Item that you selected above.


About Standard Manual Activities

About the Standard Manual Activity

Use a Standard Manual activity in your processes when you have a task that requires human interaction and you want to assign the task to a specific User or Role. You can use this activity to pause a process until the assigned User marks the task as complete.

A Standard Manual activity creates a task that appears on a User's My Tasks tab in BPM Web or in an Unassigned Task Pool in BPM Web.

Important Note

In order for a manual activity to make use of the business calendar, a User's profile must include a value for State and Zip Code. These are not required values for all User profiles, so you should use Access Management to ensure the profiles include this information.

The Standard Manual activity provides three basic options for assigning a task to an individual:

  • Assigning a Task to a User

  • Assigning a Task to a Role

  • Using BPM Suite to Assign a Task to a User

Notification, Escalation, and Time Options

You should complete the following options for each manual activity before you start a process:

  • Configuring Notification Options

  • Escalation Options for Manual Activities

  • Time Options for Manual Activities

Other Options

The Standard Manual activity allows you to set several other options that apply to the task they create.

  • Setting a Geography for a Standard Manual Activity

  • Selecting a Manual Task Plugin

  • Setting the Name of the Task in BPM Web

Extended Properties

The Extended Properties tab provides additional features that let you control Manual Activities in more detail:

  • Completing the Extended Properties tab for Manual Tasks

Related Topics

About the Prior Manual Activity | About the User Type Assignment Activity | About the Group Assign Activity | About the Dynamic Role Assignment Activity


Assigning a Task to a Role

While designing a process, you may know the Role that should complete a task, but it doesn't matter which User in that Role completes the task. In that situation, use a Standard Manual activity to assign a task to a Role.

When you assign a task to a Role, the assignment enters a role-specific, unassigned task pool which any User within the Role can view.

To assign a task to a role

  1. Add a Standard Manual activity to the canvas and complete the common activity properties.

    Note:
    Completing common activity properties is essential to create an organized and functional process.

  2. Click the Manual tab.

  3. Click the field in the Role row.
    The field is highlighted and a drop-down list appears.

  4. Select the Role to which you want to assign the task.

  5. Set the Time Options.

    Note:
    Setting the time options allows you to control when a task will escalate or time out.

  6. If you want the task to escalate, set the Escalation Options.

  7. Optional: Configure the Notification Options and Additional Options.

  8. Complete the Extended Properties tab.

  9. Click OK.
    The Properties for Activity window closes.

When the activity executes, it will place the task into a role-specific, unassigned task pool that only users in the role you selected can view.


Assigning a Task to a User

Processes often require human interaction in order to be completed. To achieve the necessary human interaction to complete a process, use a Standard Manual activity to assign a task to a specific user within your organization.

To assign a task to a user

  1. Add a Standard Manual activity to the canvas and complete the common activity properties.

    Note:
    Completing common activity properties is essential to create an organized and functional process.

  2. Click the Manual tab.

  3. Click the field in the Role row.
    The field is highlighted and a drop-down list appears.

  4. Select the Role of the User to whom you want to assign this task.
    The Role appears in the field and a drop-down list appears in the second row.

  5. Click the User Name drop-down list and select a User to whom you want to assign the task.

  6. Set the Time Options.

    Note:
    Setting the time options allows you to control when a task will escalate or time out.

  7. If you want the task to escalate, set the Escalation Options.

  8. Configure the Notification Options if you want to send a notification to the User.

  9. Complete the Extended Properties tab.

  10. Click OK.
    The Properties window closes.

When the activity executes, it will assign the manual task to the User you selected.


Setting a Geography for a Standard Manual Activity

When you select a Role to perform a task, and allow BPM Suite to auto-assign the task to a User in that Role, you can also specify the Geography in which the User receiving the task must be a member.

To set a geography

  1. Click the Manual tab.

  2. Click the Geography button.

  3. Select the Consider Geography when assigning this task option.
    The options in the group box become enabled.

  4. Choose either Select or Use Data Item for the Geography Set option.
    If you choose Select, use the drop-down list to select a Geography Set now.
    If you choose Use Data Item, use the drop-down list to select the Data Item that will contain the name of a Geography Set at run time.

  5. Choose either Select or Use Data Item for the Geography option.
    If you choose Select, use the drop-down list to select a Geography. If you chose Use Data Item earlier for the Geography Set, you will not be able to select a Geography in this window. If you define the Geography Set at run time, you must also define the Geography at run time.
    If you choose Use Data Item, you can use the drop-down list to select the Data Item that will contain the name of a Geography at run time.

  6. Click OK.


Using BPM Suite to Assign a Task to a User

If you do not know which User you should assign a task to, and you do not want the task to enter an unassigned task pool, use BPM Suite to automatically assign a task to a User within a Role.

When you use BPM Suite to automatically assign a task, it uses a default set of criteria (workload, activity experience, time since last activity interaction, etc.) to assign the task to the most eligible user.

To use the system to assign a task to a User

  1. Add the Standard Manual activity to the designer canvas and complete the common activity properties.

    Note:
    Completing common activity properties is essential to create an organized and functional process.

  2. Click the Manual tab.

  3. Select the Auto-assign task based on Role option.

  4. Click the empty field in the Role row and select a Role.

  5. Set the Time Options.

    Note:
    Setting the time options allows you to control when a task will escalate or time out.

  6. If you want the task to escalate, set the Escalation Options.

  7. Optional: Configure the Notification Options and Additional Options.

  8. Complete the Extended Properties tab.

  9. Click OK.
    The Properties for Activity window closes.

When the activity executes, it will use the BPM system to automatically assign the task to a User within the Role you selected.


About the Task Completion Activity

Every process has a unique Workflow ID. If you provide the Workflow ID of a process, you can complete a manual activity in any one, specific process.

You can retrieve the Workflow ID of a process by using the Table Reader activity to query any one of several database tables in the BPM database that contain Workflow IDs.

You should be able to find the Workflow ID in any of the following tables:

  • FlowDataItemValue

  • FlowStart

  • TaskConsolidation

  • TaskAssignment

Every process belongs to a process group (even if it is the only process in that group) and every process group is uniquely identified by an SOEID. You can identify a process by providing the SOEID, but there is an important limitation.

If the process group contains multiple instances of the same process (for example, if you used the Multi-instance Sub-Process activity to start multiple instances of one process) then the SOEID will actually identify every instance of a process within the process group. This means that if you use the SOEID to identify a process where you want to complete a manual activity, this activity will complete the manual activity in every instance of the process.

You might or might not want to complete the manual activity in every instance of the process. Be sure to consider this behavior as you configure this activity.

You can retrieve the SOEID of a process by using the Table Reader activity to query any one of several database tables in the BPM database that contain SOEIDs.

You should be able to find the SOEID in any of the following tables:

  • FlowDataItemValue

  • FlowStart

  • TaskConsolidation

  • TaskAssignment

About the Task Completion Activity

You can use the Task Completion Activity to complete, timeout, or cancel a manual activity. This is useful in circumstances like the following:

  • You have multiple manual activities that need to be assigned concurrently, but when one is completed the other becomes unnecessary.

  • An action in one process makes a manual activity in another process unnecessary.

The Task Completion activity can complete manual activities in any process—even a process other than the one that contains the Task Completion activity (called an "unrelated process instance"). However, if you want to complete a manual activity in an unrelated process, you will need to provide the Workflow ID of that process or the SOEID of the Process Group.

Completing a Manual Activity in a Single Instance of a Process

If you use this method to identify the process that contains the manual activity you want to complete, then this activity will only complete the manual activity in one specific instance of that process.

  • Completing a Manual Activity in a Single Instance of the Current Process

  • Completing a Manual Activity in a Single Instance of an Unrelated Process

Completing a Manual Activity in Multiple Instances of a Process

If you use this method to identify the process that contains the manual activity you want to complete, then this activity will complete the manual activity in every instances of the process within a Process Group.

  • Completing a Manual Activity in Multiple Instances of the Current Process

  • Completing a Manual Activity in Multiple Instances of an Unrelated Process

Mapping values to Visible Data Items in the Manual Activity

If you choose to complete the activity normally (rather than timeout or cancel the activity), then you can map values to the Data Items in the activity.

  • Mapping Values to Visible Data Items in the Activity to Complete

Required Auxiliary Topics

Before you begin configuring a Task Completion Activity, make sure to complete the following:

  • Create Data Items that will store the form information the activity will use


Select the Data Item option.

Click the Data Item drop-down list and select the UserID Data Item that either:

Contains the UserID number of the BPM User who you want to impersonate when completing the task.

or

Was used to store User Assignment Persistence information in another manual activity.

Select the User option.

Click the drop-down list to show a list of BPM Users who are able to complete the manual activity. The list of users is limited to those who are in the Role specified within the manual activity you are completing.

Completing a Manual Activity in a Single Instance of an Unrelated Process

You can use the Task Completion Activity to complete a manual task in a specific, single instance of an unrelated process (i.e. a process other than the one that contains the Task Completion Activity).

To Complete a Manual Activity in a Single Instance of an Unrelated Process

  1. Add the Task Completion Activity to the canvas and complete the common activity properties.

  2. Click the Task Completion Activity tab.

  3. Click the ellipsis button next to the Process box.
    A window displays a list of all processes in the current environment.

  4. Locate the process that contains the manual activity you want to complete.

  5. Select the process and click OK.

  6. Click the Manual activity drop-down list and select the manual activity that you want to complete.

  7. Click the Completion option drop-down list and select the method you want to use to complete the manual activity:

    • Mark as Complete - Completes the activity normally, allowing you to submit values for each Data Item visible in the manual activity

    • Force Timeout - Skips the activity with the reason that it was not completed in time

    • Force Cancellation - Cancels the activity and stops the current path in the process from finishing (although alternate paths around the activity will continue)

  8. If you selected Mark as Complete, then map values to the visible Data Items in the activity to complete.

  9. Select the Workflow ID option.

  10. Click the drop-down list and select the Data Item that will contain the Workflow ID of the process that contains the manual activity you want to complete.

  11. Select the user to impersonate using one of the following methods:

    • Select a Data Item

    • Select a specific User

  12. Click OK.
    The Properties window closes.

Related Topics

Completing a Manual Activity in Multiple Instances of an Unrelated Process | Completing a Manual Activity in a Single Instance of the Current Process | Completing a Manual Activity in Multiple Instances of the Current Process


Select the Data Item option.

Click the Data Item drop-down list and select the UserID Data Item that either:

Contains the UserID number of the BPM User who you want to impersonate when completing the task.

or

Was used to store User Assignment Persistence information in another manual activity.

Select the User option.

Click the drop-down list to show a list of BPM Users who are able to complete the manual activity. The list of users is limited to those who are in the Role specified within the manual activity you are completing.

Completing a Manual Activity in a Single Instance of the Current Process

You can use the Task Completion Activity to complete a manual task in a specific, single instance of the current process (i.e. the process that contains the Task Completion Activity).

To Complete a Manual Activity in a Single Instance of the Current Process

  1. Add the Task Completion Activity to the canvas and complete the common activity properties.

  2. Click the Task Completion Activity tab.

  3. Click the ellipsis button next to the Process box.
    A window displays a list of all processes in the current environment.

  4. Locate the current process.

  5. Select the process and click OK.

  6. Click the Manual activity drop-down list and select the manual activity that you want to complete.

  7. Click the Completion option drop-down list and select the method you want to use to complete the manual activity:

    • Mark as Complete - Completes the activity normally, allowing you to submit values for each Data Item visible in the manual activity

    • Force Timeout - Skips the activity with the reason that it was not completed in time

    • Force Cancellation - Cancels the activity and stops the current path in the process from finishing (although alternate paths around the activity will continue)

  8. If you selected Mark as Complete, then map values to the visible Data Items in the activity to complete.

  9. Select the Workflow ID option and select the WorkflowID option.

  10. Select the user to impersonate using one of the following methods:

    • Select a Data Item

    • Select a specific User

  11. Click OK.
    The Properties window closes.

Related Topics

Completing a Manual Activity in Multiple Instances of the Current Process | Completing a Manual Activity in a Single Instance of an Unrelated Process | Completing a Manual Activity in Multiple Instances of an Unrelated Process


Select the Data Item option.

Click the Data Item drop-down list and select the UserID Data Item that either:

Contains the UserID number of the BPM User who you want to impersonate when completing the task.

or

Was used to store User Assignment Persistence information in another manual activity.

Select the User option.

Click the drop-down list to show a list of BPM Users who are able to complete the manual activity. The list of users is limited to those who are in the Role specified within the manual activity you are completing.

Completing a Manual Activity in Multiple Instances of an Unrelated Process

You can use the Task Completion Activity to complete a manual task in multiple instances of an unrelated process (i.e. a process other than the one that contains the Task Completion Activity). You might want to complete the activity in multiple instances of a process if you used a Multi-instance Sub-Process activity to start multiple, concurrent instances of the same process.

To Complete a Manual Activity in Multiple Instances of an Unrelated Process

  1. Add the Task Completion Activity to the canvas and complete the common activity properties.

  2. Click the Task Completion Activity tab.

  3. Click the ellipsis button next to the Process box.
    A window displays a list of all processes in the current environment.

  4. Locate the process that contains the manual activity you want to complete.

  5. Select the process and click OK.

  6. Click the Manual activity drop-down list and select the manual activity that you want to complete.

  7. Click the Completion option drop-down list and select the method you want to use to complete the manual activity:

    • Mark as Complete - Completes the activity normally, allowing you to submit values for each Data Item visible in the manual activity

    • Force Timeout - Skips the activity with the reason that it was not completed in time

    • Force Cancellation - Cancels the activity and stops the current path in the process from finishing (although alternate paths around the activity will continue)

  8. If you selected Mark as Complete, then map values to the visible Data Items in the activity to complete.

  9. Select the SOEID option.

    Important
    The SOEID identifies a Process Group. If you use this value to identify the process that contains the manual activity you want to complete, then this activity will complete that activity in every instance of the process.

  10. Click the drop-down list and select the Data Item that will contain the SOEID of the process that contains the manual activity you want to complete.

  11. Select the user to impersonate using one of the following methods:

    • Select a Data Item

    • Select a specific User

  12. Click OK.
    The Properties window closes.

Related Topics

Completing a Manual Activity in a Single Instance of an Unrelated Process | Completing a Manual Activity in a Single Instance of the Current Process | Completing a Manual Activity in Multiple Instances of the Current Process


Select the Data Item option.

Click the Data Item drop-down list and select the UserID Data Item that either:

Contains the UserID number of the BPM User who you want to impersonate when completing the task.

or

Was used to store User Assignment Persistence information in another manual activity.

Select the User option.

Click the drop-down list to show a list of BPM Users who are able to complete the manual activity. The list of users is limited to those who are in the Role specified within the manual activity you are completing.

Completing a Manual Activity in Multiple Instances of the Current Process

You can use the Task Completion Activity to complete a manual task in multiple instances of the current process (i.e. the process that contains the Task Completion Activity). You might want to complete the activity in multiple instances of a process if you used a Multi-instance Sub-Process activity to start multiple, concurrent instances of the same process.

To Complete a Manual Activity in Multiple Instances of the Current Process

  1. Add the Task Completion Activity to the canvas and complete the common activity properties.

  2. Click the Task Completion Activity tab.

  3. Click the ellipsis button next to the Process box.
    A window displays a list of all processes in the current environment.

  4. Locate the current process.

  5. Select the process and click OK.

  6. Click the Manual activity drop-down list and select the manual activity that you want to complete.

  7. Click the Completion option drop-down list and select the method you want to use to complete the manual activity:

    • Mark as Complete - Completes the activity normally, allowing you to submit values for each Data Item visible in the manual activity

    • Force Timeout - Skips the activity with the reason that it was not completed in time

    • Force Cancellation - Cancels the activity and stops the current path in the process from finishing (although alternate paths around the activity will continue)

  8. If you selected Mark as Complete, then map values to the visible Data Items in the activity to complete.

  9. Select the SOEID option and select the SOEID option.

    Important
    The SOEID identifies a Process Group. If you use this value to identify the process that contains the manual activity you want to complete, then this activity will complete that activity in every instance of the process.

  10. Select the user to impersonate using one of the following methods:

    • Select a Data Item

    • Select a specific User

  11. Click OK.
    The Properties window closes.

Related Topics

Completing a Manual Activity in a Single Instance of the Current Process | Completing a Manual Activity in a Single Instance of an Unrelated Process | Completing a Manual Activity in Multiple Instances of an Unrelated Process


Mapping Values to Visible Data Items in the Activity to Complete

If you decide to complete a manual activity using the Mark as Complete option, then you can provide values that will be used for the Data Items in the manual activity.

Note

Only the Data Items that are made visible in the manual activity will be available through this activity.
If you change the list of visible Data Items in the manual activity, you need to save the changes to the process before the Data Items will become available in the Task Completion Activity.

You can provide values for the visible Data Items by entering values now or by mapping the visible Data Items to other Data Items.

To Map Values to the Visible Data Items in the Activity

  1. If you have not already done so, use the Task Completion Activity to select the process and manual activity you want to complete:

    • Completing a Manual Activity in a Single Instance of an Unrelated Process

    • Completing a Manual Activity in a Single Instance of the Current Process

    • Completing a Manual Activity in Multiple Instances of an Unrelated Process

    • Completing a Manual Activity in Multiple Instances of the Current Process

    Note
    Be sure to select the Mark as Complete completion option and be sure the Data Items you want to populate are visible in the manual activity.

  2. Look through the Manual Task Data Item column to find any Data Item you want to populate.

  3. Click the Source cell in the same row as the Data Item you want to populate.

  4. Select one of the following options to define the source of the value you will give the Data Item:

    • DataItem.DisplayValue - The Display Value of a Data Item

    • DataItem.Value - The Value of a Data Item

    • Constant - Any string of text or numbers you enter now

  5. Perform one of the following actions, depending on the Source you selected:

    • If you selected DisplayValue or Value, then click the Value cell in the same row and select the Data Item you want to use to populate that information in the manual activity.

    • If you selected Constant, then click the Value cell in the same row and enter the value you want to use to populate that information in the manual activity.

  6. Define the process instance.

  7. Select the BPM User to impersonate.

  8. Click OK.
    The Properties window closes.

Related Topics

About the Task Completion Activity | Mapping Values to Visible Data Items in the Activity to Complete | Defining the Process Instance


About User Type Assignment Activities

About the User Type Assignment Activity

You can use the User Type Assignment activity to assign a task to a User who fits a certain description, even without knowing who that User is. For example, you could assign a task to the User who started the process, the User who owns the process, or a User who has a relationship to another User.

  • Process Initiator
    This option assigns the task to the user responsible for starting the process.

  • Process Owner
    This option assigns the task to the user who owns the process, which is defined in the Process Properties window, under the Process Owner Information tab.

  • User Relationship
    This option allows you to assign based on a work Relationship defined in a User's User Profile.

  • Data Item
    This option allows you to assign this task to a User whose ID is held in a Data Item. The Data Item must be a User ID type.

The following list details task assignment methods that you can create using the User Type Assignment Activity:

  • Assigning a Task based on a User ID Data Item

  • Assigning a Task to the User that Started the Process

  • Assigning a Task to the Process Owner

  • Assigning a Task to a User's Manager

  • Assigning a Task Using the Organizational Chart

Other Options

The Standard Manual activity allows you to set other options that apply to the task they create.

  • Selecting a Manual Task Plugin

  • Setting the Name of the Task in BPM Web

Required Auxiliary Topics

If you are assigning a task based on a User ID, then you need to create a Data Item to store the User ID of the User to which you want to assign the task.

  • Creating a User ID Data Item

An essential part of assigning user type assignment activities is successfully completing the extended properties tab.

  • Completing the Extended Properties tab for Manual Tasks

Furthermore, you should complete the following options for each manual activity before you initiate a process.

  • Configuring Notification Options

  • Escalation Options for Manual Activities

  • Time Options for Manual Activities


Assigning a Manual Activity to the Process Owner

Assigning a Task to the Process Owner

To assign a task to the creator or user responsible for a process, configure a User Type Assignment Activity to assign it to the process owner.

The process owner is defined in the Process Properties window, under the Process Owner Information tab.

To assign a task to the owner of a process

  1. Add the User Type Assignment Activity to the designer canvas and complete the common activity properties.

    Note:
    Completing common activity properties is essential to create an organized and functional process.

  2. Click the User Type tab.

  3. Using the Assignment Method drop-down list box, select Process Owner.
    Process Owner     appears in the Assignment Method list box field and the white table under the list box is grayed out.

  4. Set the Time Options.

    Note:
    Setting the time options allows you to control when a task will escalate or time out.

  5. If you want the task to escalate, set the Escalation Options.

  6. Optional: Configure the Notification Options and Additional Options.

  7. Complete the Extended Properties tab.

  8. Click OK.
    The Properties for Activity window closes.

When the activity executes, it will assign the task is to the owner of the process.


Assigning a Manual Activity to the User that Started the Process

Assigning a Task to the User that Started the Process

Processes often start because of the actions of a User, whether he/she submits a budget table, a customer order, or some other form of data.

Later in a process, you may need to assign work to a User who understands why the process started. In this instance, you can use the User Type Assignment activity to assign a task to the User that started the process.

To assign a task to the user who started a process

  1. Add the User Type Assignment Activity to the designer canvas and complete the common activity properties.

    Note:
    Completing common activity properties is essential to create an organized and functional process.

  2. Click the User Type tab.

  3. Using the Assignment Method drop-down list, select Process Initiator.
    Process Initiator     appears in the Assignment Method drop-down list field and the white table under the drop-down list is grayed out.

  4. Set the Time Options.

    Note:
    Setting the time options allows you to control when a task will escalate or time out.

  5. If you want the task to escalate, set the Escalation Options.

  6. Optional: Configure the Notification Options and Additional Options.

  7. Complete the Extended Properties tab.

  8. Click OK to close the Properties window.

When the activity executes, it will assign the task to the user that started the process.


Assigning a Manual Activity Using the Organizational Chart

Assigning a Task Using the Organizational Chart

Organizational charts outline hierarchical relationships of responsibility, a function that you can use to design processes.

Using BPM Designer's Organizational Chart feature, you can assign tasks to high-responsibility users (i.e. Managers, Supervisors, CEOs, CFOs, CTOs) based on the relationships they have to subordinate users in your organization's hierarchy.

When you assign a task using an organizational chart, you assign it to a user that is one level higher in the organization's hierarchy from the base user that you start at.

Example:

If you assign a task to a user's manager, you can use BPM Designer's Organizational Chart to assign the task to the manager's supervisor.

Important
The organizational chart in BPM Designer must be completed in order for this function to work.

To assign a task using an organizational chart

  1. Add the User Type Assignment activity to the designer canvas and complete the common activity properties.

    Note:
    Completing common activity properties is essential to create an organized and functional process.

  2. Click the User Type tab.

  3. Assign a user to the task using one of following choices:

  • Assign the task to the process Owner

  • Assign the task to the user that Began a Process

  • Assign a task using a User ID

  • Assign a task based on the user's relation ship to another user

  4. Click the Assign to User's Parent Role (as defined via the org chart) checkbox.

  5. Set the Time Options.

    Note:
    Setting the time options allows you to control when a task will escalate or time out.

  6. If you want the task to escalate, set the Escalation Options.

  7. Optional: Configure the Notification Options and Additional Options.

  8. Complete the Extended Properties tab.

  9. Click OK.
    The Properties for Activity window closes.

When the activity executes, it will assign the task to a user a level up in your organization's hierarchy, relative to the first user you identified.


Assigning a Task Based on a User ID Data Item

If you know a User's User ID, and his/her User ID is stored in a Data Item entered into the current process you are designing, then you can configure a User Type Assignment activity to assign a task to a User ID.

To assign a task based on a User ID data item

  1. Add the User Type Assignment Activity to the designer canvas and complete the common activity properties.

    Note:
    Completing common activity properties is essential to create an organized and functional process.

  2. Click the User Type tab.

  3. Using the Assignment Method drop-down list, select Data Item.
    A Data Item drop-down list appears under the Assignment Method drop-down list.

  4. Using the Data Item drop-down list, select the Data Item that is storing the User ID of the user you want to assign this task to.

    Note:
    To get User ID Data Items to appear in the Data Item list, the process must contain the User ID Data Item of the user to which you want to assign the task.

  5. Set the Time Options.

    Note:
    Setting the time options allows you to control when a task will escalate or time out.

  6. If you want the task to escalate, set the Escalation Options.

  7. Optional: Configure the Notification Options and Additional Options.

  8. Complete the Extended Properties tab.

  9. Click OK.
    The Properties for Activity window closes.

When the activity executes, it will assign the task to the user that corresponds to User ID Data Item you selected.


Assigning a Task To a User's Manager

You can use the User Type Assignment Activity to assign a task to a User's manager, as defined in the User's profile.

By default, the only user relationship defined in the user profile window is the User's manager. You can set a User's manager by modifying the user profile. Also, with the assistance of a developer, you can add custom values to the User Profile window in order to create new User relationships.

To assign a task to a User's manager

  1. Add the User Type Assignment Activity to the Canvas and complete the common activity properties.

    Note:
    Completing common activity properties is essential to create an organized and functional process.

  2. Click the User Type tab.

  3. Click the Assignment Method drop-down list and select User Relationship.
    A table with the labels Prior Task, User Profile, and User Relationship appears under the Assignment Method drop-down list.

  4. Click the drop-down list in the Prior Task row and select an activity that occurs earlier in the current process.

  5. Click the drop-down list in the User Profile row and select User Profile.

  6. Click the drop-down list in the User Relationship row and select UP_ManagerUserID.
    The activity will assign this task to the manager of the User who is assigned the task in the activity you selected.

  7. Set the Time Options.

    Note:
    Setting the time options allows you to control when a task will escalate or time out.

  8. If you want the task to escalate, set the Escalation Options.

  9. Optional: Configure the Notification Options and Additional Options.

  10. Complete the Extended Properties tab.

  11. Click OK to close the Properties window.

When the activity executes, it will assign the task to the user that has the user relationship identified in the user's User Profile.


About Manual Activity Extended Properties

After you have configured the basic features of a Manual Activity, you may want to configure other, more detailed options as well. You can achieve more control over your Manual Activities by using the Extended Properties tab.

To access the extended properties tab

  1. Add a Manual Activity to the designer.

  2. Double-click the activity's icon.
    The Properties window opens.

  3. Click the Extended Properties tab.

Properties you can configure in the Extended Properties tab

  • Give or restrict a User's access to Data Items

  • Generate an InfoPath form through which users can complete the manual activity

  • Generate an ASP.NET web form through which users can complete the manual activity

  • Generate the Web Service Description Language to retrieve the URL and specification

  • Define how Data Items appear and behave

  • Define what sort of values Data Items can accept

  • Save the User assigned to a specific activity to use again later for a related activity

Fill in the Extended Properties sub-tabs according to the following information:

  • Task Plug-in

  • WSDL

  • Data Item Display

  • Data Item Validation

  • User Persistence

Related Topics

Understanding BPM Activities


CAP - Manual Activities

  1. Click the Manual Activities category in the Toolbox.

  2. Double-click the activity you want to add, or drag it to the Canvas.
    The activity is added to the process.

  3. Open the Properties for the activity (double-click the activity or right-click and select Activity Properties).
    The Properties window appears.

  4. Complete the common activity properties.


Configuring Notification Options

When a User is assigned a manual activity, you can notify the User via Email or SMS.

Note:

You should not set the Notification Options until you have defined the User who will receive the task. If you set Notification Options before that, they will not be saved when you click OK.

To configure the notification options

  1. While configuring a Standard Manual Task or Prior Manual Task, click the Manual tab. If configuring a User Type Assignment task, click the User Type tab.

  2. Click the Notification Options button.
    The Notification window opens.

  3. Use the following table to configure a notification option.

    Notification option

    How to configure

    Email

    Click the Email check box and then click the Configure button across from the Email check box.

    SMS

    Click the SMS check box to send an SMS to the assigned user when tasked.

  4. When you are finished, click OK.


Escalation Options - Manual Activity

Setting Escalation Options for Manual Activities

When assigning a task, you can set how a task will escalate (i.e. reassign to a different user) if it is not completed by its original assignee.

Note:

You only have to set the escalation options if you want the task to escalate. If you checked the time out check box, the escalation options section will be grayed out.

To set escalation options for manual activities

  1. While configuring a Standard Manual Task or Prior Manual Task, click the Manual tab. If configuring a User Type Assignment task, click the User Type tab.

  2. Locate the escalation options section.

  3. Set the escalation options according to the following table.

For the

Complete the following

Escalation Interval

Select the Days, Hours, and Minutes between each escalation interval.

If you want the task to timeout after the escalations, whether it be one, two, or three, select the Timeout after escalations option.

User Information

For each Escalation User Information field, complete the following:

  • Click the right column in the Role row.

  • From the drop-down list, select a specific role or {Use Org Chart}.

  • If you selected a role, then the task will be assigned to a user in that role or you can select a user from the User Name row, which contains only users in that role.

  • If you selected {Use Org Chart}, then the task will be assigned to a user in the assigned user's parent role or you can select a user from the User Name list, which contains only users in the parent role based on the Org Chart.

Note:
You can escalate a task up to three times.

Important:
If you are escalating a task, you need to select a parent role. If you do not define a parent role, then the task will not escalate and simply delay the process. Be sure to either select a parent role or select Timeout Task from the Time Options section (See Time Options). Or click the Timeout after escalation check box to ensure the process continues even after the task has been escalated.


Time Options - Manual Activity

Time Options for Manual Activities

You can set the time options of a Manual Activity to determine how much time a User will be given to complete a task. You can also choose to make a task escalate or time out when time runs out.

To set the time options for manual activities

  1. While configuring a Standard Manual Task or Prior Manual Task, click the Manual tab. If configuring a User Type Assignment task, click the User Type tab.

  2. Locate the time options section.

  3. Set the time options according to the following table.

For the

Complete the following

Time Source

  1. Select either the Data Item that will contain the amount of time to wait for this user to complete the task or select Fixed duration.

  2. If you select Fixed duration, enter the number of days, hours, and minutes you want to give this user to complete the task.

    Note:
    Eight (8) hours represents eight real-time hours in the context of the Business Calendar. If the Business Calendar does define working and non-working hours, then this time will not count off-hours.

    The Group Assign Activity does not take into account the Business Calendar.

    Example:     If the Business Calendar defines working and non-working hours and a task is assigned at 1:00 P.M. on Friday and the work day ends at 5:00 P.M., the user has until Monday at Noon to finish the task, assuming the user does not work on weekends and starts at 8:00 A.M. Monday.

  3. If you select a data item, make sure the data item contents are formatted properly.

After time expires

  • Click Escalate Task to escalate the task to another user when time expires.

    Note:
    You will need to complete the Escalation Settings.

  • Click Timeout Task to set the task's status to "timed out"

    Note:
    If you choose to Timeout a Task, then you cannot complete the Escalation Settings.


About the Create CRM 3.0 Entity Activity

You can use the Create CRM 3.0 Entity activity to create almost anything that can exist in Microsoft CRM 3.0. For example, you could create any of the following entities, plus many more:

  • An account

  • A case

  • A contract

  • A lead

  • An opportunity

  • A quote

When you create a CRM entity, you can also set the values for the properties of that entity. Finally, you can select a Data Item that will store a "key" value that you can use to reference the same entity again later.

  • Creating a CRM 3.0 Entity

Required Auxiliary Topics

Before you begin configuring the Create CRM 3.0 Entity activity, make sure to complete the following:

  • Create Data Items that will store property values and the entity key.


Creating a CRM 3.0 Entity

You can use the Create CRM 3.0 Entity activity to create almost anything that can exist in Microsoft CRM 3.0.

To create a CRM 3.0 Entity

  1. Add the Create CRM 3.0 Entity activity to the Canvas and complete the common activity properties.

  2. Click the Create CRM 3.0 Entity tab.

  3. If you have not already done so, click the Change Settings button and configure the CRM server settings.

  4. Click the CRM entity drop-down list and select the type of CRM entity you want to create.

  5. Under Entity key, select either Use Data Item or Enter value.

    Note:
    The "key" value for a CRM entity is the value that you can enter to manipulate the same CRM entity again later.

    If you selected Use Data Item, click the drop-down list and select the Data Item that contains the value you want to set as the "key" for this entity.
    If you selected Enter value, enter the value that you want to set as the "key" for this entity.

  6. Click the Property field and select one of the properties that applies to the CRM entity you chose.
    The Type field changes to reflect the type of value required by the property you selected.

  7. Click the Source field and select Data Item Value, Data Item Display Value, or Constant.

    If you selected Data Item Value, the Value field will use the value of the Data Item you select.
    If you selected Data Item Display Value, the Value field will use the display value of the Data Item you select.
    If you selected Constant, you will be able to enter the value you want to use at design time.

  8. Click the Value field and enter the value you want to submit for the selected option, or select the Data Item that will contain that value at run time.

  9. Repeat steps 6 - 8 to set values for as many properties as necessary.

    Note:
    If you know that you want to enter a value for every possible property, you can select the     List all properties option to add every property to the grid quickly.

  10. Click OK.
    The Properties window closes.


About the Delete CRM 3.0 Entity Activity

About the Delete CRM 3.0 Entity

You can use the Delete CRM 3.0 Entity activity to delete almost anything that exists in Microsoft CRM 3.0. For example, you could delete any of the following types of entities, plus many more:

  • An account

  • A case

  • A contract

  • A lead

  • An opportunity

  • A quote

When you delete a CRM entity, you need to select the type of entity and the entity key, which is the unique value that identifies the exact entity you want to delete.

  • Deleting a CRM 3.0 Entity

Required Auxiliary Topics

Before you begin configuring the Delete CRM 3.0 Entity activity, make sure to complete the following:

  • Create Data Items that will store the entity key.


Deleting a CRM 3.0 Entity

You can use the Delete CRM 3.0 Entity activity to delete almost anything that can exist in Microsoft CRM 3.0.

To delete a CRM 3.0 Entity

  1. Add the Delete CRM 3.0 Entity activity to the Canvas and complete the common activity properties.

  2. Click the Delete CRM 3.0 Entity tab.

  3. If you have not already done so, click the Change Settings button and configure the CRM server settings.

  4. Click the CRM entity drop-down list and select the type of CRM entity you want to delete.

  5. Under Entity key, select either Use Data Item or Enter value.

    Note:
    The "key" value for a CRM entity is a value that uniquely identifies entities in CRM that you have already created through BPM Suite.

    If you selected Use Data Item, click the drop-down list and select the Data Item that contains the "key" value of the entity you want to delete.
    If you selected Enter value, enter the key value of the entity you want to delete.

  6. Click OK.
    The Properties window closes.


About the Retrieve CRM 3.0 Entity Activity

You can use the Retrieve CRM 3.0 Entity activity to retrieve almost any information that exists in Microsoft CRM 3.0. For example, you could retrieve any of the following types of information, plus many more:

  • An account

  • A case

  • A contract

  • A lead

  • An opportunity

  • A quote

When you retrieve a CRM entity, you need to provide the key value that you defined when you created that entity through BPM Suite. You also need to select Data Items to contain the properties of the entity that you want to retrieve.

  • Retrieving a CRM 3.0 Entity

Required Auxiliary Topics

Before you begin configuring the Retrieve CRM 3.0 Entity activity, make sure to complete the following:

  • Create Data Items that will store property values and the entity key.


Retrieving a CRM Entity

You can use the Retrieve CRM 3.0 Entity activity to retrieve any property of any existing entity in Microsoft CRM 3.0.

To retrieve a CRM 3.0 Entity

  1. Add the Retrieve CRM 3.0 Entity activity to the Canvas and complete the common activity properties.

  2. Click the Retrieve CRM 3.0 Entity tab.

  3. If you have not already done so, click the Change Settings button and configure the CRM server settings.

  4. Click the CRM entity drop-down list and select the type of CRM entity you want to update.

  5. Under Entity key, select either Use Data Item or Enter value.

    Note:
    The "key" value for a CRM entity is a value that uniquely identifies entities in CRM that you have already created through BPM Suite.

    If you selected Use Data Item, click the drop-down list and select the Data Item that contains the key value of the entity you want to retrieve.
    If you selected Enter value, enter the key value of the entity you want to retrieve.

  6. Click the Data Item field and select the Data Item that you want to contain the value of the property you are going to retrieve.

  7. Click the Property field and select one of the properties that applies to the CRM entity you chose.

  8. If necessary, select the Clear Existing Values option to remove any other values that might be in the Data Item you selected.

  9. Repeat steps 6 - 8 to select Data Items to store as many properties as necessary.

  10. Click OK.
    The Properties window closes.


About the Update CRM 3.0 Entity Activity

You can use the Update CRM 3.0 Entity activity to update almost anything that exists in Microsoft CRM 3.0. For example, you could update any of the following types of entities, plus many more:

  • An account

  • A case

  • A contract

  • A lead

  • An opportunity

  • A quote

When you update a CRM entity, you need to provide the key value that you defined when you created that entity through BPM Suite. When you update a CRM entity, you can also set the values for the properties of that entity.

  • Updating a CRM 3.0 Entity

Required Auxiliary Topics

Before you begin configuring the Update CRM 3.0 Entity activity, make sure to complete the following:

  • Create Data Items that will store property values and the entity key.


Updating a CRM 3.0 Entity

You can use the Update CRM 3.0 Entity activity to update any property of any existing entity in Microsoft CRM 3.0.

To update a CRM 3.0 Entity

  1. Add the Update CRM 3.0 Entity activity to the Canvas and complete the common activity properties.

  2. Click the Update CRM 3.0 Entity tab.

  3. If you have not already done so, click the Change Settings button and configure the CRM server settings.

  4. Click the CRM entity drop-down list and select the type of CRM entity you want to update.

  5. Under Entity key, select either Use Data Item or Enter value.

    Note:
    The "key" value for a CRM entity is a value that uniquely identifies entities in CRM that you have already created through BPM Suite.

    If you selected Use Data Item, click the drop-down list and select the Data Item that contains the key value of the entity you want to update.
    If you selected Enter value, enter the key value of the entity you want to update.

  6. Click the Property field and select one of the properties that applies to the CRM entity you chose.
    The Type field changes to reflect the type of value required by the property you selected.

  7. Click the Source field and select Data Item Value, Data Item Display Value, or Constant.

    If you selected Data Item Value, the Value field will use the value of the Data Item you select.
    If you selected Data Item Display Value, the Value field will use the display value of the Data Item you select.
    If you selected Constant, you will be able to enter the value you want to use at design time.

  8. Click the Value field and enter the value you want to submit for the selected option, or select the Data Item that will contain that value at run time.

  9. Repeat steps 6 - 8 to set values for as many properties as necessary.

    Note:
    If you know that you want to enter a value for every possible property, you can select the     List all properties option to add every property to the grid quickly.

  10. Click OK.
    The Properties window closes.


CAP - CRM 3.0 activities

  1. Click the Microsoft CRM Activities category in the Toolbox.

  2. Double-click the activity you want to add, or drag it to the Canvas.
    The activity is added to the process.

  3. Open the Properties for the activity (double-click the activity or right-click and select Activity Properties).
    The Properties window appears.

  4. Complete the common activity properties.


Configuring the CRM 3.0 Server Settings

Before you can configure the CRM 3.0 activities to do anything, you need to set up a connection to the Microsoft CRM server. After you set up a connection in one CRM activity, every other CRM activity will be set to the same connection.

To set up a connection to the CRM server

  1. Add the CRM activity to the Canvas and complete the common activity properties.

    Note:
    Completing common activity properties is essential to creating an organized and functional process.

  2. Under Microsoft Dynamics CRM 3.0 server settings, click the Change Settings button.

  3. Click the Metadata Web Service field and enter the address of the CRM Web service that handles metadata.

    Example:
    http://<servername>/mscrmservices/2006/metadataservice.asmx

  4. Click the Execution Web Service field and enter the address of the CRM Web service that executes CRM requests.

    Example:
    http://<servername>/mscrmservices/2006/crmservice.asmx

  5. Click the Login field and Enter your CRM login.

    Note:
    Your login should be in the format Domain\Login.

  6. Click the Password field and enter your CRM password.

  7. Click Test Connection. If the connection is valid, a window confirms the connection. If the connection fails, make sure you entered the correct information.

  8. Click OK to close the CRM 3.0 Server Settings window.

Related Topics

About the Create CRM 3.0 Entity Activity | About the Delete CRM 3.0 Entity Activity | About the Retrieve CRM 3.0 Entity Activity | About the Update CRM 3.0 Entity Activity


About the Create SharePoint List Item Activity

You can use the Create SharePoint List Items activity to add SharePoint 2007 list items while working in BPM Designer. For example, you could create any of the following types of information:

  • A calendar entry

  • A task

  • A document

In order to create SharePoint list items through BPM Suite, you need to provide the SharePoint Web address, select the SharePoint list, and specify the items you wish to create. While performing these actions, you may select Data Items that will contain the Web address, the list, or the property of the entity that you want to create.

  • Creating a SharePoint 2007 List Item

Required Auxiliary Topics

Before you begin configuring the Create SharePoint 2007 List Item activity, make sure to complete the following:

  • Create Data Items that will store property values.


Create SharePoint List Item

Creating a SharePoint 2007 List Item

You can use the Create SharePoint 2007 List Item activity to add list items to any Microsoft SharePoint 2007 list such as a Calendar, Task List, Document Library, or Image List.

To create a SharePoint List Item

  1. Add the Create List Items activity to the Canvas and complete the common activity properties.

  2. Click the Create List Item tab.
    The Destination List tab, Map Values tab, and the Documents to Upload tab appear.

  3. On the Destination List tab, under SharePoint site, click Select Data Item

    -    or-

    click Enter site URL.

    If you click Select Data Item, click the drop-down list, and then click the Data Item that will be the SharePoint Web address.
    If you select Enter site URL, type the SharePoint address containing the list where items will be created, or click Edit to include Data Item values with the address you typed.

    Tip:
    Instead of typing long addresses, copy the address from the address bar in your Web browser, and then paste the selection in Enter site URL.

  4. Click the Use BPM Engine Credentials option

    -    or-

    click the Enter Credentials button.

    If you click Use BPM Engine Credentials, the rights and privileges of the server's username will direct your access.
    If you click Enter Credentials, complete this dialogue box to authenticate to the SharePoint site using the information you use to log on to your network.

  5. Under SharePoint list, click Select Data Item

    -or-

    click Enter list name.

    If you click Select Data Item, click the drop-down list, and then click the Data Item that will contain the list name where the item will added.
    If you click Enter list name, type the list name you want to use, or click Refresh Names, and then click the desired list name in the drop-down list. When you click Refresh Names, your computer connects to the SharePoint site and retrieves all list names available.

    Note:
    If you previously used DataItems in the Web address, you will be prompted to enter values for each item in order to compose the address.

  6. Click the Map Values tab.

  7. In the lower left corner of Map input values, click the Retrieve Columns button.
    The Map input values grid, except the Value column, fills with all column information from the SharePoint list you specified in Step 5.

    Note:
    If you previously used DataItems for the Web address, you will be prompted to enter values for each item in order to compose the address. If you selected DataItems in Step 1 and Step 5, those items will be used when you click Retrieve Columns.
    If the selection for the Source column is either DataItem.Display or DataItem.Value, click the Value column field to display a drop-down arrow, and then click a Data Items. Data Items designated as FilePointer will not display.

  8. Click the Documents to Upload tab.

  9. Select The list being added to is a document library check box only if the SharePoint list is a Document Library. This area will allow you to select a file to add to the library.

  10. Click Network file

    -or-

    click FilePointer Data Item.

    If you click Network file, click Browse, click the file you want to add to the SharePoint document library. Make sure your sever can access the file.
    If you click FilePointer Data Item, click the drop-down list, and then click the file you want to upload.

    Note:
    In List item attachments, click the Data Item you wish to include as an attachment to your new list item.

  11. Click OK.
    The Properties for Activity window closes.

Related Topics
About the Create SharePoint List Item activity | Creating a Data Item


About the Create SharePoint Site Activity

About the SharePoint Create Site Activity

The SharePoint Create Site activity is used to create SharePoint Web sites and portals.

  • Creating a SharePoint Site

Required Auxiliary Topics

Before you begin configuring the SharePoint Create Site activity, make sure to complete the following:

  • Create Data Items


Creating a SharePoint Site

The SharePoint Create Site activity is used to create SharePoint Web sites and portals.

Important:

To create a SharePoint site, you will need to enter the username and password of a user that belongs to the local Administrators group on the server running SharePoint, or you can enter the name of a user that belongs to the Microsoft Windows NT security group account that is identified as the SharePoint Administrator Group Account.

To create a SharePoint site

  1. Add the SharePoint Create Site activity to the Canvas and complete the common activity properties.

  2. Click the SharePoint Create Site tab.
    The SharePoint Authentication tab is displayed by default.

  3. Under SharePoint username, click Select Data Item

    -or-

    click Enter value.

    If you select     Select Data Item, click the drop-down list, and then click the Data Item that will contain the username of the user that the activity will use to access the SharePoint.
    If you select     Enter value, enter the username.

    Note:
    When entering the username, the domain is also required and should be entered as follows:     DOMAIN\username

  4. Under SharePoint password, choose the Select Data Item option and then select the Data Item that will contain the password of the user selected or entered in step 3 or choose the Enter value option and enter the password of the user selected or entered in step 3.

  5. Under SharePoint Admin URL, choose the Select Data Item option, and then select the Data Item that will contain the URL to the SharePoint admin Web service that will be called to create the site.

    -or-

    Choose the Enter value option and enter the URL.

    Note:
    The Admin URL will use the following format:     http://<server name>:<port number/_vti_adm/Admin.asmx

  6. Click the Site Details tab.

  7. Under Title, enter the title of the new SharePoint site in the Title field.
    The title is displayed on each page of the site.

    Note:
    To include Data Item values in the title, select a Data Item from the Data Items drop-down list, and then click Insert Display Value to insert the Data Item's display value or click the Insert Value to insert the Data Item's value. The Data Item will appear with percent signs around it in the title with either .DisplayValue or .Value appended to the XML Tag of the selected Data Item. You can manually enter Data Items if you know the correct syntax, which is %DataItem.DisplayValue% or %DataItem.Value%.

  8. Under Description, enter a description for the new SharePoint site in the Description field.

  9. Under URL name, enter the complete URL for the new SharePoint site in the URL name field.

  10. Click the Site Owner tab.

  11. Under Site owner's username, choose the Select Data Item option and then select the Data Item that will contain the username of the site owner, or choose the Enter value option and enter the username.

  12. Under Site owner's display name, choose the Select Data Item option and then select the Data Item that will contain the name of the site owner, or choose the Enter value option and enter the name of the site owner.

  13. Under Site owner's email address, choose the Select Data Item option and then select the Data Item that will contain the email address of the site owner, or choose the Enter value option and enter the email address of the site owner.

  14. Click the Site Portal tab.

  15. Under Portal URL enter the URL that users can use to access the SharePoint site.

    Note:
    The portal URL does not have to be the same as the URL you entered in the     URL name field on the Site Details tab.

    Example:
    The URL name could be     http://sharepoint-server/sites/bpm and the Portal URL could be http://sharepoint.bluespringsoftware.com/bpm.

  16. Under Portal name, enter the name of this SharePoint site that you want to appear when looking at a list of SharePoint sites.

  17. Click the Site Template tab.

  18. Under Site Template, choose the Select Data Item option, and then select the Data Item that contains one of the following template numbers, or choose the Enter value option and enter one of the following template numbers:

    Template number     (Description)
    STS#0 (Team site)
    STS#1 (Blank site)
    STS#2 (Document workspace)
    MPS#0 (Basic meeting workspace)
    MPS#1 (Blank meeting workspace)
    MPS#2 (Decision meeting workspace)
    MPS#3 (Social meeting workspace)
    MPS#4 (Multipage meeting workspace)

  19. Under Data Item to store site URL, select a Data Item to hold the final URL of the SharePoint site that gets created.

  20. Click OK.
    The     Properties for Activity window closes.

Related Topics

About the Create SharePoint Site activity


About the Delete SharePoint List Item Activity

About the Delete SharePoint Item Activity

You can use the Delete SharePoint List Item activity to delete SharePoint 2007 list items while working in BPM Designer. For example, you could delete any of the following types of information:

  • A calendar entry

  • A task

  • A document

In order to delete SharePoint list items through BPM Suite, you need to provide the SharePoint Web address, select the SharePoint list, and specify the items you wish to create. While performing these actions, you may select Data Items that will contain the Web address, the list, or the property of the entity that you want to create.

  • Deleting a SharePoint 2007 List Item

Required Auxiliary Topics

Before you begin configuring the Delete SharePoint 2007 List Item activity, make sure to complete the following:

  • Create Data Items that will store property values.


Deleting a SharePoint Item

Deleting a SharePoint 2007 List Item

You can use the Delete SharePoint 2007 List Item activity to delete items from any Microsoft SharePoint 2007 list such as a calendar, task, or document.

Important:
Except for Web addresses, the values you type in this procedure are case sensitive.

To delete a SharePoint List Item

  1. Add the Delete List Items activity to the Canvas and complete the common activity properties.

  2. Click the Delete List Items tab.

  3. In SharePoint site, click Select Data Item

    -    or-

    click Enter site URL.

    If you click Select Data Item, click the drop-down list, and then click the Data Item that will be the SharePoint Web address.
    If you select Enter site URL, type the address of the SharePoint site that contains the list from where items will be deleted, or click Edit to include Data Item values with the address you typed.

  4. Click the Use BPM Engine Credentials option

    -    or-

    click the Enter Credentials button.

    If you click Use BPM Engine Credentials, the rights and privileges of the server's username will direct your access.
    If you click Enter Credentials, complete this dialogue box to authenticate to the SharePoint site using the information you use to log on to your network.

  5. In SharePoint list, click Select Data Item

    -or-

    click Enter list name.

    If you click Select Data Item, click the drop-down list, and then click the Data Item that will contain the list name where the item will added.
    If you click Enter list name, type the list name you want to use, or click Refresh Names, and then click the desired list name in the drop-down list. When you click Refresh Names, your computer connects to the SharePoint site and retrieves all list names available.

  6. In List items to update, click Delete all list items

    -or-

    click Only delete list items where the following condition is met.

    If you select Delete all list items, all available list items will be chosen for updating.
    If you select Only delete list items where the following condition is met, you can specify conditions to meet before updating list items.

  7. Click OK.
    The Properties for Activity window closes.


About the Retrieve SharePoint List Item Activity

You can use the Retrieve SharePoint List Item activity to retrieve SharePoint 2007 list items while working in BPM Designer. For example, you could retrieve a calendar entry or a task.

In order to retrieve SharePoint list items through BPM Suite, you need to provide the SharePoint Web address, select the SharePoint list, and specify the items you wish to create. While performing these actions, you may select Data Items that will contain the Web address, the list, or the property of the entity that you want to create.

  • Retrieving a SharePoint 2007 List Item

Required Auxiliary Topics

Before you begin configuring the Retrieve SharePoint 2007 List Item activity, make sure to complete the following:

  • Create Data Items that will store property values.


Retrieving a SharePoint Item

Retrieving a SharePoint 2007 List Item

You can use the Retrieve SharePoint 2007 List Item activity to retrieve items from any Microsoft SharePoint 2007 list such as a calendar entry or a task.

Important:
Except for Web addresses, the values you type in this procedure are case sensitive.

To retrieve a SharePoint List Item

  1. Add the Retrieve List Items activity to the Canvas and complete the common activity properties.

  2. Click the Retrieve List Item tab.
    The List Items to Retrieve tab is selected by default.

  3. In SharePoint site, click Select Data Item

    -    or-

    click Enter site URL.

    If you click Select Data Item, click the drop-down list, and then click the Data Item that will be the SharePoint Web address.
    If you select Enter site URL, type the SharePoint address that contains the list items to be retrieved. You can click Edit to include Data Item values with the address you typed.

  4. Click the Use BPM Engine Credentials option

    -    or-

    click the Enter Credentials button.

    If you click Use BPM Engine Credentials, the rights and privileges of the server's username will direct your access.
    If you click Enter Credentials, complete this dialogue box to authenticate to the SharePoint site using the information you use to log on to your network.

  5. In SharePoint list, click Select Data Item

    -or-

    click Enter list name.

    If you click Select Data Item, click the drop-down list, and then click the Data Item that will contain the list name where the item will added.
    If you click Enter list name, type the list name you want to use, or click Refresh Names, and then click the desired list name in the drop-down list. When you click Refresh Names, your computer connects to the SharePoint site and retrieves all list names available.

    Note:
    If you previously used DataItems in the Web address, you will be prompted to enter values for each item in order to compose the address.

  6. In List items to update, click Retrieve all list items

    -or-

    click Only retrieve list items where the following condition is met.

    If you select Retrieve all list items, all available list items will be chosen for updating.
    If you select Only retrieve list items where the following condition is met, you can specify conditions to meet before updating list items.

  7. Click the Map Values tab.

  8. In the lower left corner of Map input values, click the Retrieve Columns button.
    The Map input values grid, except the Value column, fills with all column information from the SharePoint list you specified in Step 5.

    Note:
    If you previously used DataItems for the Web address, you will be prompted to enter values for each item in order to compose the address. If you selected DataItems in Steps 1 and 5, those values will be used when you click Retrieve Columns.
    If the selection for the Source column is either DataItem.Display or DataItem.Value, click the Value column field to display a drop-down arrow, and then click a Data Items. Data Items designated as FilePointer will not display.

  9. Under Map input values, complete the table grid.

a. In the List Column column, click the drop-down arrow, and then select a SharePoint column title.

b. In the Data Item column, type a value.

Note:
If the selection for the Source column is either DataItem.Display or DataItem.Value, the Value column will contain a drop-down arrow that you click for Data Items. Data Items designated as FilePointer will not appear.

  10. Click OK.
    The Properties for Activity window closes.

Related Topics
About the Retrieve SharePoint List Item activity | Creating a Data Item


About the Update SharePoint List Item Activity

You can use the Update SharePoint List Items activity to update SharePoint 2007 list items while working in BPM Designer. For example, you could update any of the following types of information:

  • A calendar entry

  • A task

  • A document meta data

In order to update a SharePoint list item through BPM Suite, you need to provide the SharePoint Web address, select the list, and specify which items you wish to update. In doing so, you may need to select Data Items to contain the properties of the entity that you want to update.

  • Updating a SharePoint 2007 List Item

Required Auxiliary Topics

Before you begin configuring the Update SharePoint 2007 List Item activity, make sure to complete the following:

  • Create Data Items that will store property values.


Updating a SharePoint List Item

Updating a SharePoint 2007 List Item

You can use the Update SharePoint 2007 List Item activity to update items in any Microsoft SharePoint 2007 list. For example, you could update a Calendar, Task List, a Document Library, or an Image List.

Important:
Except for Web addresses, the values you type in this procedure are case sensitive.

To update a SharePoint List Item

  1. Add the Update List Items activity to the Canvas and complete the common activity properties.

  2. Click the Update List Item tab.
    The List Items to Update tab is selected by default.

  3. Under the SharePoint site, click Select Data Item

    -    or-

    click Enter site URL.

    If you click Select Data Item, click the drop-down list, and then click the Data Item that will be the SharePoint Web address.
    If you click Enter site URL, type the SharePoint address that contains the list items to be updated. You can click Edit to include Data Item values with the address you typed.

  4. Click the Use BPM Engine Credentials option

    -    or-

    click the Enter Credentials button.

    If you click Use BPM Engine Credentials, the rights and privileges of the server's username will direct your access.
    If you click Enter Credentials, complete this dialogue box to authenticate to the SharePoint site using the information you use to log on to your network.

  5. In SharePoint list, click Select Data Item

    -or-

    click Enter list name.

    If you click Select Data Item, click the drop-down list, and then click the Data Item that will contain the list name where the item will added.
    If you click Enter list name, type the list name you want to use, or click Refresh Names, and then click the desired list name in the drop-down list. When you click Refresh Names, your computer connects to the SharePoint site and retrieves all list names available.

    Note:
    If you previously used DataItems in the Web address, you will be prompted to enter values for each item in order to compose the address.

  6. In List items to update, click Update all list items

    -or-

    click Only update list items where the following condition is met.

    If you select Update all list items, all available list items will be chosen for updating.
    If you select Only update list items where the following condition is met, options are enabled that allow you to specify conditions to be met before updating list items.

  7. Click the Map Values tab.

  8. In the lower left corner of Map input values, click the Retrieve Columns button.
    The Map input values grid, except the Value column, fills with all column information from the SharePoint list you specified in Step 5.

    Note:
    If you previously used DataItems for the Web address, you will be prompted to enter values for each item in order to compose the address. If you selected DataItems in steps 1 and 5, those values will be used when you click Retrieve Columns.
    If the selection for the Source column is either DataItem.Display or DataItem.Value, click the Value column field to display a drop-down arrow, and then click a Data Items. Data Items designated as FilePointer will not display.

  9. In the Map input values grid, preform the following steps:

a. In the Source column, click the down arrow and select a value.

Note:
If the selection for the Source column is either DataItem.Display or DataItem.Value, the Value column will contain a down arrow you can click for Data Items except for those designated FilePointer.

b. In the Value column, type a value.

c. In the List Column column, click the down arrow and select a SharePoint column title.

Note:
You can download attachments if your SharePoint list allows and a Data Item is designated as a FilePointer.

  10. Click OK.
    The Properties for Activity window closes.


CAP - SharePoint

  1. Click the Microsoft SharePoint category in the Toolbox.

  2. Double-click the activity you want to add, or drag it to the Canvas.
    The activity is added to the process.

  3. Open the Properties for the activity (double-click the activity or right-click and select Activity Properties).
    The Properties window appears.

  4. Complete the common activity properties.


Enter Credentials

  1. Under SharePoint user name, click Select Data item

    -    or-

    click Enter value.

    If you click Select Data Item, click the down arrow, and select the Item that corresponds to your username.
    If you click Enter value, type the username you use to access your network.

  2. Under SharePoint password, click Select Data Item

    -or-

    click Enter value.

    If you click Select Data Item, click the down arrow, and select a Data Item that contains a SharePoint password.
    If you click Enter value, type the password used in association with the username in Step 1.

    Note:
    These credentials will be stored in the activity configuration. Previously indicated credentials will be replaced.

  3. Select the SharePoint Domain check box.
    This field allows you to indicate the domain name of your network.

  4. Click Select Data Item

    - or-

    click Enter value.

    If you click Select Data Item, select the Data Item that contains the domain name of your network.
    If you click Enter value, type the domain name of your network.

  5. Click OK.
    You return to Properties.


Include Data Items

  1. Click the Data Items down arrow.
    Your Data Items will appear in the drop-down list.

  2. Click either Insert Display Value

    -or-

    Click Insert Value.

    Note:
    If you click Insert Display Value, you will insert the Data Item's display value.
    If you click Insert Value, you will insert the Data Item's value.
    The Data Item will appear with percent signs around it in the title with either .DisplayValue or .Value appended to the XML Tag of the selected Data Item.


Map Values

  1. Click the Retrieve Columns button.
    Designer retrieves column titles from the SharePoint list and stores them in List Column.

    Note:
    If you have used Data Items in this procedure, the Preview URL form displays. This form allows, you to enter a test value for the Data Item. The result of this form will be used as the site URL to search for lists.

  2. In the Source column, click the drop-down arrow, and then select a value.

    Note:
    If the row's Source column selection is DataItem.Display or DataItem.Value, the Value column will be a drop-down list that contains all Data Items except for items designated FilePointer.

  3. In the Value column, click the drop-down arrow, and then select a value.

    Note:
    If the row's Source column selection is not DataItem.Display or DataItem.Value, type your selection in the blank field.

  4. In List Column, select the desired SharePoint list column name.

  5. In List item attachments, you can specify files to upload to the new list item.

    Note:
    You can download attachments if your SharePoint list allows and a Data Item is designated as a FilePointer.


Refresh Columns

  1. Click Refresh Columns.
    Designer retrieves column titles from the SharePoint list designated in the previous step.

    Note:
    If you have used Data Items in this form, the Preview URL form displays. This form will allow you to enter a test value for the Data Item. The results of this form will be used as the site URL to probe or lists.

  2. In Column to query, click the drop-down list, and then click the desired item.
    In the next step, you will indicate how you wish to compare your Column to query selection to the Data Item or SharePoint list item column value.

  3. In Type of comparison, click the drop-down list, and then click a value.

  4. In Compare list item column value to, click Select Data Item

    -or-

    click Enter constant.

    If you click Select Data Item, click the drop-down list, and then click the value to be used in the updated items query.
    If you click Enter constant, type the value to be used in the updated items query.


url Edit button

  1. Select a Data Item from the Data Items drop-down list.
    In the URL box, the location of your pointer in the address will determine the placement of the selected Item.

  2. Click Insert Display Value

    - or-

    Click the Insert Value to insert the Data Item value.

    If you click Insert Display Value, the Data Item display value will be inserted into the SharePoint site address.
    If you click Insert Value, the Data Item value will be inserted into the Sharepoint site address.

    Note:
    The Data Item will appear beginning and ending with percent signs. Either .DisplayValue or .Value will be added to the XML Tag of the selected Data Item. You can manually enter Data Items if you know the correct syntax, which is %DataItem.DisplayValue% or %DataItem.Value%.

  3. Click Preview URL.
    A screen displays test values to preview, allowing you to add a URL in the right column.

  4. Click Preview URL.
    Your address displays in the URL field.

  5. Click OK.
    You will return to Properties for Activities when you click OK once more.

  6. Click OK.


About the FTP Activity

You can use the FTP activity to send and retrieve files from an FTP server. The activity retrieves the file name and server address from Data Items.

Follow the links below to learn how to send and retrieve files using the FTP Activity:

  • Retrieving a File from a Remote Server via FTP

  • Sending a File to a Remote FTP Server

Required Auxiliary Topics

Before you configure an FTP activity, you need to create Data Items to store the files you send and retrieve.

  • Creating Data Items

If sending or retrieving entire files, you need to create a FilePointer Data Item to store the name of the file.

  • Creating a FilePointer Data Item


Retrieving a File from a Remote Server via FTP

You can use the FTP Activity to retrieve files from a remote FTP server.

To retrieve a file from a remote server via FTP

  1. Add the FTP activity to the designer canvas and complete the common activity properties.

  2. Click the FTP tab.

  3. In the FTP tab, click the Send/Receive tab.

  4. Select the Retrieve File(s) from Remote Server radio button.
    The Retrieving Files section is highlighted.

  5. Enter the search string for the remote file or get the search string from a data item in the drop-down list.

  6. Choose a data item to store the retrieved files in.

    Note:
    The data item can be stored in any of these locations, depending on file type.

  7. Click the Remote Server Info tab.

  8. In the Remote Server field, enter the name of the remote server.

    Example Data Item Value:
    ftp://bpm.bluespringsoftware.com

    Note:
    If the name of the remote server is stored in a Data Item, then select the Data Item from the Available Data Items list.
    The Data Item appears in the Remote Server field with percent signs (%) around it, which indicates the Data Item value will be used when the process runs.

  9. In the User Name fields, enter the user name (or select the Data Item that contains the user name) for accessing the FTP site.

  10. In the Password fields, enter the password (or select the Data Item that contains the password) for accessing the FTP site.

  11. In the Remote Path field, enter the path to the remote server.

    Note:
    If the name of the directory path is stored in a Data Item or you want to construct the path dynamically, then select the Data Item from the Available Data Items list. Then, click the Add to Remote Path button.
    The Data Item appears in the Directory Path on Remote Server field with percent signs (%) around it, which indicates the Data Item value will be used when the process runs.

    You can add multiple Data Items to the field to build the directory path.

    Example:
    %Partner_Folder%/%Software%/%Title%-%Version%/

  12. Click the OK button.
    The Properties for Task window closes.

Related Topics

About the FTP Activity


Sending a File to a Remote Server via FTP

You can use the FTP Activity to send files/information from a process to a remote server.

To send a file to a remote server via FTP

  1. Add the FTP activity to the designer canvas and complete the common activity properties.

  2. Click the FTP tab.

  3. In the FTP tab, click the Send/Receive tab.

  4. Select the Send File to Remote Server radio button.
    The Send File(s) to a Remote Server section is highlighted.

  5. Select a data item to send to the remote server

    Note:
    The data item can be stored in any of these locations, depending on file type.

  6. Click the Remote Server Info tab.

  7. In the Remote Server field, enter the name of the remote server.

    Example Data Item Value:
    ftp://bpm.bluespringsoftware.com

    Note:
    If the name of the remote server is stored in a Data Item, then select the Data Item from the Available Data Items list.
    The Data Item appears in the Remote Server field with percent signs (%) around it, which indicates the Data Item value will be used when the process runs.

  8. In the User Name fields, enter the user name (or select the Data Item that contains the user name) for accessing the FTP site.

  9. In the Password fields, enter the password (or select the Data Item that contains the password) for accessing the FTP site.

  10. In the Remote Path field, enter the path to the remote server.

    Note:
    If the name of the directory path is stored in a Data Item or you want to construct the path dynamically, then select the Data Item from the Available Data Items list. Then, click the Add to Remote Path button. The Data Item appears in the Directory Path on Remote Server field with percent signs (%) around it, which indicates the Data Item value will be used when the process runs.

    You can add multiple Data Items to the field to build the directory path.

    Example:
    %Partner_Folder%/%Software%/%Title%-%Version%/

  11. Click the OK button.
    The Properties for Task window closes.

Related Topics

About the FTP Activity


About the HTTP Activity

You can use the HTTP activity to get and post information to a Web resource and, if desired, receive information back from that file. You can get or post an entire XML document referenced by a single Data Item or by individual XML tags stored in Data Items.

  • Making a HTTP Get or Post Request

Required Auxiliary Topics

Before you begin configuring a HTTP activity, make sure to create Data Items to store the HTTP Post's inputs and outputs.

  • Creating Data Items


Configuring HTTP Proxy Settings

Configuring the HTTP Proxy Settings

If the resource you are requesting uses a proxy server, you will need to configure the HTTP Proxy Settings.

To Configure the HTTP Proxy Settings

  1. Select the Proxy Settings Required check box.

  2. Click the Proxy Settings button.
    The HTTP Proxy Settings window will appear.

  3. Enter the IP address of the proxy server through one of the following methods:

    • Select a Data Item from the Select Data Item drop-down menu, or

    • Enter a static proxy server in the Enter proxy server field

  4. Enter the port number used to access the proxy server through one of the following methods:

    • Select a Data Item from the Select Data Item drop-down menu, or

    • Enter a static port number in the Enter proxy port field

  5. Enter the user name used to access the proxy server through one of the following methods:

    • Select a Data Item from the Select Data Item drop-down menu, or

    • Enter a static user name in the Enter user name field

  6. Enter the password corresponding to the user name you entered to access the proxy server through one of the following methods:

    • Select a Data Item from the Select Data Item drop-down menu, or

    • Enter a static password in the Enter user password field

  7. Click OK.
    The HTTP Proxy Settings window will close.

Related Topics

Specifying the Web Resource, About the HTTP Activity


Configuring the HTTP Request

You can set header values and query elements before sending the HTTP request. In order to do so, you must configure the request.

To Configure the Request

  1. Select how you would like activities to be marked if the HTTP request times out:

    • Select the Mark activity as failed option to mark the activity as failed; the log will note that the activity did not receive a response in the given amount of time and is configured to fail.

    • Select the Mark activity as timed out option to mark the activity as timed out; the log will note that the activity did not receive a response in the given amount of time and is configured to time out.

Note:
The Mark activity as failed option is selected by default.

  2. Enter the request headers you wish to include in your HTTP request into the Request headers grid.

    1. To create a new request header, click the Header field and enter the name of the header you would like to send in your request.

    2. Select one of the following sources from the Source drop-down list:

      • Constant

      • DataItem.DisplayValue

      • DataItem.Value

    3. Enter the value of the header into the Value field:

      • If you specified the source as a constant, enter a static value into the Value field.

      • If you chose a DataItem.DisplayValue or a DataItem.Value, select the DataItem you wish to use from the Value drop-down list.

    4. Repeat steps 1 - 4 for each request header you wish to create.

  3. Select the type of HTTP request you would like to make

    • To make a Get request, select the Get option: the query elements will be passed in the URL's query string

    • To make a Post request, select the Post option: the query elements will be posted to the web resource

      Note:
      The Get option is selected by default.

  4. Enter the query or form elements you wish to request into the Query elements grid.

    1. To create a new query element, click the Query Element field and enter the name of the element you would like to query in your request.

      Note:
      If you are performing a Post request, you may also request form elements; consequently, the Query elements group box is labeled Query/Form elements, and Query Element field is labeled the Query/Form Element.

    2. Select one of the following sources from the Source drop-down list:

      • Constant

      • DataItem.DisplayValue

      • DataItem.Value

    3. Enter the value of the header into the Value field:

      • If you specified the source as a constant, enter a static value into the Value field.

      • If you chose a DataItem.DisplayValue or a DataItem.Value, select a DataItem from the Value drop-down list.

    4. Repeat steps 1-4 for each query element you wish to create.

Related Topics

About the HTTP Activity, Specifying the Web Resource, Storing the HTTP Response


Making a HTTP Get or Post Request

Making a HTTP Request

You can get and post information to a Web resource using the HTTP activity. You can get all of the information in a single Data Item to a specified URL and save response information to Data Items. This option works well when posting an XML document stored in or referenced by a Data Item.

Important:
You will need to know the API being used by the site with the file you are going to access.

To Make a HTTP Get or Post Request

  1. Add the HTTP activity to the designer canvas and complete the common activity properties.

    Note:
    Completing common activity properties is essential to create an organized and functional process.

  2. Click the HTTP tab.
    The Web Resource subtab should be in front.

  3. Specify the web resource that the activity will use to make the request.

  4. Configure the HTTP request.

  5. Store the HTTP response.

  6. Click OK.
    The Properties window will close.

Related Topics

About the HTTP Activity


Specifying the Web Resource

Before making a HTTP request, you must specify the web resource you will access, including its URL, a user name and password authorized to access the web resource if necessary, the length of time before the request times out, and the proxy settings, if necessary.

To Specify the Web Resource

  1. Enter the URL of the web resources you wish to access in the URL field.

    • Optionally, if the URL address will be compiled from Data Items, click the Edit button.
      The Edit URL window will appear.

      1. Click in the URL field to enter the URL.

      2. Click the Data Items drop-down list to select a Data Item, then click the Insert Display Value or Insert Value button to add the Data Item to the URL.

      3. Optionally, click the Preview URL button to see what the URL will look like when the Data Items are replaced with actual values.

      4. Click OK when you are done writing the URL.
        The Edit URL window will close.

  2. Optionally, if the resource you are requesting requires authentication, enter an authorized user name through one of the following methods:

    • Select a Data Item from the Select Data Item drop-down menu, or

    • Enter a static user name in the Enter user name field.

  3. Optionally, if you entered a user name, you may also be required to use a password, enter a password through one of the following methods:

    • Select a Data Item from the Select Data Item drop-down menu, or

    • Enter a static password in the Enter password field.

  4. Optionally, enter the time, in seconds, that you want to wait for a connection to be made to the server.

    Note:
    The time out is set to 60 seconds by default. If you leave this field empty, BPM Suite will enter a 0 in the field when you save, indicating that there is no time out.

  5. Optionally, if the resource you are requesting uses a Proxy Server, configure the Proxy Settings.

Related Topics
About the HTTP Activity, Configuring the HTTP Request , Storing the HTTP Response


Storing the HTTP Response

You can store the values returned in the headers of a HTTP response in Data Items.

To Store Headers

  1. Click the Response sub-tab.

  2. Enter the Data Items in which you wish to store information from the response headers into the Response Header grid.

    1. To add a Data Item to the grid, select a Data Item from the Data Item drop-down list in the Response Header grid.

      Note:
      You may use each Data Item only once in this grid.

    2. Enter the name of the header you wish to store in the Source field.

      Note:
      At runtime, if the header does not exist, the activity will log that the selected header was not available, but it will not fail.

    3. If you would like to clear any pre-existing information in the Data Item before writing the response, select the Clear Existing Values box.

      Note:
      When this box is not checked, new header values are added to the existing values in the Data Item, creating a multi-instance Data Item; the Clear Existing Values box is checked by default.

  3. Select a Data Item to store the HTTP response status code in from the Data Item drop-down list in the Response status group box.

  4. Select a Data Item to store the HTTP response message in one of the following ways:

    • Store the message directly in a Data Item by selecting the Data Item you wish to store the message in from the Select Data Item drop-down list, or

    • Store the message in a file and store a pointer to the file in a Data Item:

      1. Select a FilePointer Data Item from the Select FilePointer drop-down list.

      2. Click in the File name field to enter the file name
        Optionally, if the URL address will be compiled from Data Items, click the Edit button.
        The Configure Output File Name window will appear.

        1. Click in the File name field to enter the File name.

        2. Click the Data Items drop-down list to select a Data Item, then click the Insert Display Value or Insert Value button to add the Data Item to the File name.

        3. Optionally, click the Preview File Name button to see what the URL will look like when the Data Items are replaced with actual values.

        4. Click OK when you are done entering the file name.
          The Configure Output File Name window will close.

Note:
You must enter the file extension at the end of the file name; for example, .txt or .html.

  5. Select the option that corresponds to how you want to handle the file if another file with the same name already exists:

    • Select Overwrite the file if it exists if you want the file to overwrite any other files with the same name in the same location.

    • Select Increment the file name if it exists if you want to add an incrementally higher number to the file name rather than overwrite files with the same name. An incrementally higher file name has a number appended to the end. For example, FileName.xls would become FileName_1.txt, and then FileName_2.txt.

  6. Click OK.
    The Properties window will close.

Related Topics
A bout the HTTP Activity, Configuring the HTTP Request, Specifying the Web Resource


About the HTTP Post Activity

You can use the HTTP Post activity to post information to a Web resource and, if desired, receive information back from that file. You can post an entire XML document referenced by a single Data Item or you can post individual XML tags stored in Data Items.

  • Posting a Single Data Item to a Web Resource

  • Posting Multiple Data Items to a Web Resource

Required Auxiliary Topics

Before you begin configuring a HTTP Post activity, make sure to create Data Items to store the HTTP Post's inputs and outputs.

  • Creating Data Items


HTTP Properties Table

For the

Do the following

URL

Enter the URL for the file you want to request in the URL field.

Example:
http://www.BluespringSoftware.com/process-http/

User Name

Optional: If the resource you are requesting requires authorization, enter an authorized user name in the User Name field.

User Password

Optional: If you entered a user name, you may also have to send your password. If so, enter the password in the User Password field.

Time Out

Optional: In the Time Out field, enter the time in seconds that you want to wait for a connection to be made to the server.

Note:
By default, the time out is set to 60 seconds.

If you leave this field empty, BPM Suite will enter a 0 in the field when you save, which tells it that there is no timeout.

User Proxy Server

If the resource you are requesting uses a Proxy Server, click the Use Proxy Server field, then click the down-arrow button, and then select True. Otherwise, leave False as the default value.

If you selected True, then complete the following information:

  • In the Proxy Server field, enter the IP address of the Proxy Server.

  • In the Proxy Port field, enter the port used to access the Proxy Server.

  • In the Proxy User Name field, enter your user name used to access the Proxy Server.

  • In the Proxy User Password field, enter your password used to access the Proxy Server.

Use SSL

If the resource you are requesting requires SSL, then click the Use SSL field, then click the down-arrow button, and then select True. Otherwise, leave False as the default value.

If you selected True, double-click the Use SSL field. The SSL Certificate Name field appears. In the SSL Certificate Name field, enter the name of the SSL certificate used with this page.


Multiple Data Item Information - HTTP

  • Name
    In the Name field, enter the name used by the file you request to access information.

  • Source
    In the Source field, select either Constant, Data Item.DisplayValue, or Data Item.Value. Most of the time, Data Item.DisplayValue and Data Item.Value are the same, but they can be different.

    Example:
    The Data Item.DisplayValue may be yes, but the Data Item.Value may be 1.

  • Value
    In the Value field, either enter a value if you selected Constant from the Source drop-down list or select the Data Item you want to use if you selected Data Item.DisplayValue or Data Item.Value from the Source drop-down list.

    Note:
    You don't have to post information from a Data Item. In the Name field, enter a name used by the file to access this information, then select Constant from the Source drop-down list, and enter information in the Value field that you want to post. The information in the Value field is accessible through the name you entered.


Posting a Single Data Item to a Web Resource

You can use the HTTP Post activity to post all of the information in a single Data Item to a specified URL. This option works well when posting an XML document stored in or referenced by a Data Item.

Important:
You will need to know the API being used by the site with the file you are going to access.

To Post a Single Data Item to a Web Resource

  1. Add the HTTP Post activity to the designer canvas and complete the common activity properties.

    Note:
    Completing common activity properties is essential to create an organized and functional process.

  2. Click the HTTP Post tab.
    The Data Items tab should be displayed on the HTTP Post tab.

  3. Select the Data Items you want to use with this activity by first selecting a Data Item in the Available Data Items list, and then click the Add button.
    The Data Item appears in the Selected Data Items list.

    Note:
    To use all of the available Data Items, click the Add All Data Items button.

  4. Click the Connection tab.

  5. Using the Data Item to hold return STATUS drop-down list, select the Data Item you want to hold the return status from the server.

    Note:
    The only Data Items that will appear in this list will be the Data Items you added to the Selected Data items list on the Data Items tab.

    Example:
    If the server does not locate the file you request, it will return a 404 status code, which means the page was not found. If the server returns a 200 status code, then the file you requested was found and successfully processed. You may need this status code in a later task or for branching purposes.

  6. Using the Data Item to hold return STREAM drop-down list, select the Data Item you want to hold the stream of information returned by the server.

    Note:
    The only Data Items that will appear in this list will be the Data Items you added to the Selected Data items list on the Data Items tab.

    The information returned by the server will be HTML, XML, or plain text.

  7. If desired, click the Write to File checkbox and designate an XML file name for the returned data.

  8. In the HTTP Properties field, complete the necessary information. Refer to the HTTP Properties Table for guidance.

  9. Click the Message Content tab.

  10. Using the Content Type drop-down list, select one of the following:

    • application/x-www-form-urlencoded
      This option is the default option for posting information to a URL.

    • text/xml
      If you are posting XML, then you should select this option.

  11. Select the Use Single Data Item radio button.

  12. From the drop-down list next to Single Data option, select the Data Item with the file or single value you want to post to the resource.

    Note:
    The data item can be stored in any of these locations, depending on file type.

  13. Click the OK button to close the Properties window.

Related Topics

About the HTTP Activity


Posting Multiple Data Items to a Web Resource

You can use the HTTP Post activity to post multiple values to a resource. This option works well when you need to make explicit name-value pairings.

Important:
You will need to know the API being used by the site with the file you are going to access.

To post multiple data items to a web resource

  1. Add the HTTP Post activity to the designer canvas and complete the common activity properties.

  2. Click the HTTP Post tab.
    The Data Items tab should be displayed on the HTTP Post tab.

  3. Select the Data Items you want to use with this activity by first selecting a Data Item in the Available Data Items list, and then click the Add button [image].
    The Data Item appears in the Selected Data Items list.

    Note:
    To use all of the available Data Items, click the Add All Data Items button [image].

  4. Click the Connection tab.

  5. Using the Data Item to hold return STATUS drop-down list, select the Data Item you want to hold the return status from the server.

    Note:
    The only Data Items that will appear in this list will be the Data Items you added to the Selected Data items list on the Data Items tab.

    Example:
    If the server does not locate the file you request, it will return a 404 status code, which means the page was not found. If the server returns a 200 status code, then the file you requested was found and successfully processed. You may need this status code in a later task or for branching purposes.

  6. Using the Data Item to hold return STREAM drop-down list, select the Data Item you want to hold the stream of information returned by the server.

    Note:
    The only Data Items that will appear in this list will be the Data Items you added to the Selected Data items list on the Data Items tab.

    The information returned by the server will be HTML, XML, or plain text.

  7. If desired, click the Write to File checkbox and designate an xml file name for the returned data.

  8. In the HTTP Properties field, complete the necessary information. Refer to the HTTP Properties Table for guidance.

  9. Click the Message Content tab.

  10. Using the Content Type drop-down list, select one of the following:

    • application/x-www-form-urlencoded
      This option is the default option for posting information to a URL.

    • text/xml
      If you are posting XML, then you should select this option.

  11. Select the Multiple Data Items radio button.
    The table under the Multiple Data Items radio button becomes enabled.

  12. Fill in the table with the necessary information for each data item you want to post. Refer to this multiple data item information table for help.

  13. Click the OK button.
    The Properties for Activity window closes.

Related Topics

About the HTTP Activity


About the WebDAV Copy or Move File

About the WebDAV Copy or Move File Activity

WebDAV is an internet communication protocol that is similar to FTP, but with additional features. You can use the WebDAV activities to access and modify files that are stored in a WebDAV repository.

The WebDAV Copy or Move File activity allows you to select a file on a WebDAV repository and create a copy of that file at a different location in the WebDAV repository or move the file to a different location in the WebDAV repository.

Before you can copy or move files in a WebDAV repository, you need to enter authentication credentials.

  • Entering WebDAV Authentication Credentials

After you enter your authentication credentials, you can configure the activity to copy or move any file in a WebDAV repository.

  • Copying or Moving a WebDAV File

Required Auxiliary Topics

Before you configure the WebDAV Copy or Move File activity, you may need to create Data Items that will store your WebDAV credentials or help construct the address to the WebDAV files.

  • Creating Data Items

Related Topics

About the WebDAV Delete File Activity | About the WebDAV Get File Activity | About the WebDAV Get File Structure Activity | About the WebDAV Put File Activity


Copying or Moving a File with WebDAV

You can use the WebDAV Copy or Move File Activity to select a file on a WebDAV repository and create a copy of that file at a different location in the WebDAV repository or move the file to a different location in the WebDAV repository. The beginning and ending locations of the WebDAV file can be determined by using Data Items.

To copy or move a WebDAV file

  1. Add the WebDAV Copy or Move File activity to the Canvas and complete the common activity properties.

  2. Configure the WebDAV Authentication Credentials sub-tab.

  3. Click the File to Copy or Move sub-tab.

  4. Select the Copy file option if you want to create a copy of the file at a new location. Select the Move File option if you want to move the file to a new location.

  5. If you want to overwrite an existing file with the same name, select the Overwrite existing file, if any option.

  6. In the File source section, enter the URL to the file you want to copy or move in the URL field.

  7. To use the contents of a Data Item as part of the URL:

    • Click the Data Items drop-down list and select a Data Item.

    • Click the Insert Display Value or Insert Value buttons to add the Data Item to the URL field.

  8. Optionally, click Preview URL to see what the URL will look like when the Data Items contain values.

  9. In the File destination section, enter the URL to the location where you want the copied or moved file to arrive in the URL field.

  10. To use the contents of a Data Item as part of the URL:

    • Click the Data Items drop-down list and select a Data Item.

    • Click the Insert Display Value or Insert Value buttons to add the Data Item to the URL field.

  11. Optionally, click Preview URL to see what the URL will look like when the Data Items contain values.

  12. If the destination URL includes directories that do not already exist, you can select the Create folders if they do not exist option to create the directories as necessary.

  13. Click OK.
    The Properties window closes.

Related Topics

About the WebDAV Copy or Move File Activity


About the WebDAV Delete

About the WebDAV Delete File Activity

WebDAV is an internet communication protocol that is similar to FTP, but with additional features. You can use the WebDAV activities to access and modify files that are stored in a WebDAV repository.

The WebDAV Delete File activity allows you to delete a file on a WebDAV repository.

Before you can delete a file in a WebDAV repository, you need to enter authentication credentials.

  • Entering WebDAV Authentication Credentials

After you enter your authentication credentials, you can configure the activity to delete any file in a WebDAV repository.

  • Deleting a WebDAV File

Required Auxiliary Topics

Before you configure the WebDAV Copy or Move File activity, you may need to create Data Items that will store your WebDAV credentials or help construct the address to the WebDAV files.

  • Creating Data Items

Related Topics

About the WebDAV Copy or Move File Activity | About the WebDAV Get File Activity | About the WebDAV Get File Structure Activity | About the WebDAV Put File Activity


Deleting a WebDAV File

You can use the WebDAV Delete File activity to delete a file on a WebDAV repository. The location of the WebDAV file can be determined by using Data Items.

To delete a WebDAV file

  1. Add the WebDAV Delete File activity to the Canvas and complete the common activity properties.

  2. Configure the WebDAV Authentication Credentials sub-tab.

  3. Click the File to Delete sub-tab.

  4. In the File to delete section, enter the URL to the file you want to copy or move in the URL field.

  5. To use the contents of a Data Item as part of the URL:

    • Click the Data Items drop-down list and select a Data Item.

    • Click the Insert Display Value or Insert Value buttons to add the Data Item to the URL field.

  6. Optionally, click Preview URL to see what the URL will look like when the Data Items contain values.

  7. Click OK.
    The Properties window closes.

Related Topics

About the WebDAV Delete File Activity


About the WebDAV Get

About the WebDAV Get File Activity

WebDAV is an internet communication protocol that is similar to FTP, but with additional features. You can use the WebDAV activities to access and modify files that are stored in a WebDAV repository.

The WebDAV Get File activity allows you to copy a file on a WebDAV repository to a FilePointer Data Item so that the file can be accessed as part of a process. You can also store the file properties in a Data Item.

Before you can get a file from a WebDAV repository, you need to enter authentication credentials.

  • Entering WebDAV Authentication Credentials

After you enter your authentication credentials, you can configure the activity to get any file in a WebDAV repository.

  • Getting a WebDAV File

Required Auxiliary Topics

Before you configure the WebDAV Copy or Move File activity, you may need to create Data Items that will store your WebDAV credentials or help construct the address to the WebDAV files.

  • Creating Data Items

Related Topics

About the WebDAV Copy or Move File Activity | About the WebDAV Delete File Activity | About the WebDAV Get File Structure Activity | About the WebDAV Put File Activity


Getting a WebDAV File

Getting the File Structure of a WebDAV Repository

You can use the WebDAV Get File Structure activity to copy a file on a WebDAV repository to a FilePointer Data Item. You can also copy the properties of the file to a Data Item. The location of the WebDAV file can be determined by using Data Items.

To get a WebDAV file

  1. Add the WebDAV Get File activity to the Canvas and complete the common activity properties.

  2. Configure the WebDAV Authentication Credentials sub-tab.

  3. Click the File to Get sub-tab.

  4. In the File source section, enter the URL to the file you want to copy or move in the URL field.

  5. To use the contents of a Data Item as part of the URL:

    • Click the Data Items drop-down list and select a Data Item.

    • Click the Insert Display Value or Insert Value buttons to add the Data Item to the URL field.

  6. Optionally, select the Check out file when retrieved option to prevent other users from modifying the file until you check in the file.

  7. Optionally, click Preview URL to see what the URL will look like when the Data Items contain values.

  8. In the Data Item to store file section, click the Data Item drop-down list to select the FilePointer Data Item that you want to store the file.

  9. Optionally, select the Clear existing values option to remove any previous information that might be in the FilePointer Data Item.

  10. If you want to copy the properties of the WebDAV file to a Data Item, select the Data Item to store file properties option. Then click the Data Item drop-down list and select the Data Item you want to hold the file's properties.

  11. Click OK.
    The Properties window closes.


About the WebDAV Get File Structure

About the WebDAV Get File Structure Activity

WebDAV is an internet communication protocol that is similar to FTP, but with additional features. You can use the WebDAV activities to access and modify files that are stored in a WebDAV repository.

The WebDAV Get File Structure activity allows you to retrieve a list of every file and folder in a specified folder on a WebDAV repository. You can also retrieve the list of contents within sub-directories.

Before you can retrieve the file structure of a WebDAV repository folder, you need to enter authentication credentials.

  • Entering WebDAV Authentication Credentials

After you enter your authentication credentials, you can configure the activity to retrieve the file structure of a WebDAV repository folder.

  • Getting the File Structure of a WebDAV Repository

Required Auxiliary Topics

Before you configure the WebDAV Get File Structure activity, you may need to create Data Items that will store your WebDAV credentials or help construct the address to the WebDAV files.

  • Creating Data Items

Related Topics

About the WebDAV Copy or Move File Activity | About the WebDAV Delete File Activity | About the WebDAV Get File Activity | About the WebDAV Put File Activity


Getting the File Structure of a WebDAV Repository

You can use the WebDAV Get File Structure activity to retrieve a list of every file and folder in a specified folder on a WebDAV repository. You can also retrieve the list of contents within sub-directories.

To get a the file structure of a WebDAV repository

  1. Add the WebDAV Get File Structure activity to the Canvas and complete the common activity properties.

  2. Configure the WebDAV Authentication Credentials sub-tab.

  3. Click the Get File Structure sub-tab.

  4. In the File structure to retrieve section, click the URL field and enter the URL to the folder whose contents you want to record.

  5. To use the contents of a Data Item as part of the URL:

    • Click the Data Items drop-down list and select a Data Item.

    • Click the Insert Display Value or Insert Value buttons to add the Data Item to the URL field.

  6. Optionally, select the Include subfolders option to record the contents of the folders in the selected folder.

  7. Optionally, click Preview URL to see what the URL will look like when the Data Items contain values.

  8. In the Data Item to store file list section, click the Data Item drop-down list and select the Data Item that you want to store the file structure.

  9. Optionally, select the Clear existing values option to remove any previous information that might be in the FilePointer Data Item.

  10. Click OK.
    The Properties window closes.

Related Topics

About the WebDAV Get File Structure Activity


About the WebDAV Put File

About the WebDAV Put File Activity

WebDAV is an internet communication protocol that is similar to FTP, but with additional features. You can use the WebDAV activities to access and modify files that are stored in a WebDAV repository.

The WebDAV Put File activity allows you to copy a file in a FilePointer Data Item to a WebDAV repository. If you have a Data Item that contains the properties for the file, you can also upload those file properties to the WebDAV folder. If you have checked out the WebDAV file, you can check in the file with this activity.

Before you can copy or move files in the WebDAV repository, you need to enter authentication credentials.

  • Entering WebDAV Authentication Credentials

After you enter your authentication credentials, you can configure the activity to copy or move any file in a WebDAV repository.

  • Putting a File to a WebDAV Repository

Required Auxiliary Topics

Before you configure the WebDAV Copy or Move File activity, you may need to create Data Items that will store your WebDAV credentials or help construct the address to the WebDAV files.

  • Creating Data Items

Related Topics

About the WebDAV Copy or Move File Activity | About the WebDAV Delete File Activity | About the WebDAV Get File Activity | About the WebDAV Get File Structure Activity


Putting a File to a WebDAV Repository

You can use the WebDAV Put File activity to copy a file in a FilePointer Data Item to a WebDAV repository. If you have a Data Item that contains the properties for the file, you can also upload those file properties to the WebDAV folder. If you have checked out the WebDAV file, you can check in the file with this activity.

To upload a file to a WebDAV repository

  1. Add the WebDAV Put File activity to the Canvas and complete the common activity properties.

  2. Configure the WebDAV Authentication Credentials sub-tab.

  3. Click the File and Destination sub-tab.

  4. In the Data Item containing file to put section, click the Data Item drop-down list and select the FilePointer Data Item that contains the file you want to upload to the WebDAV repository.

  5. If you also want to upload the properties of the file, select the Data Item containing file properties group box. Click the Data Item drop-down list and select the Data Item that contains the properties of the file you are uploading.

  6. In the File destination section, click the URL field and enter the URL to the folder on the WebDAV repository where you want to upload the file.

  7. To use the contents of a Data Item as part of the URL:

    • Click the Data Items drop-down list and select a Data Item.

    • Click the Insert Display Value or Insert Value buttons to add the Data Item to the URL field.

  8. Optionally, select the Create folders if they do not exist option if the URL includes folders that might not already exist on the WebDAV repository.

  9. Optionally, select the Check in file when uploading option if you previously checked out the file and you want to allow other users to modify the file after you upload it.

  10. Optionally, click Preview URL to see what the URL will look like when the Data Items contain values.

  11. Click OK.
    The Properties window closes.

Related Topics

About the WebDAV Put File Activity


About the Web Service Activity

The Web Service activity allows you to access a Web Service, submit values for the input parameters, and store the values returned through the output parameters. It is able to work with complex Web services.

If you plan to work with a specific Web service multiple times, or if you require the assistance of a Web services expert in order to configure this activity, then you should consider using the Web Services Invoker Wizard to create a template activity. Creating a template Web service activity can make it much easier and faster to access a Web service.

To Use a Web Service

  • Selecting the Web Service and Method

  • Using Authentication to Access a Web Service

  • Providing Values for the Input Parameters

  • Storing the Web Service Output Parameters

Required Auxiliary Topics

Before you begin configuring a Web Service activity, make sure to complete the following:

  • Create Data Items to store the Web service's inputs and outputs


Providing Values for the Input Parameters

After you provide the address to the Web service you want to use and select the method, you can define values to submit to the input parameters of the Web service.

To Provide Values for the Input Parameters

  1. If you have not already done so, select the Web service and method you want to invoke.

  2. If necessary, you can use authentication to access a Web service that requires authentication.

  3. Click the Input Parameters sub-tab.

  4. Locate a parameter for which you need to set a value.

  5. Click the Source cell in the same row and select one of the following options:

    • Data Item Display Value - Select this option if you want to use the Display Value of a Data Item for the parameter.

    • Data Item Value - Select this option if you want to use the Value of a Data Item for the parameter.

    • Constant - Select this option if you want to use a static string of text for the parameter.

  6. Click the Value cell in the same row and perform one of the following actions:

    • If you selected Display Value or Value, then click the cell and use the drop-down list to select a Data Item.

    • If you selected Constant, then enter a string of text and/or numbers.

  7. Repeat steps 4-6 as necessary to set more values for input parameters.

  8. Click the Output Parameters sub-tab and set up how you want to store the Web service output parameters.

  9. Click OK.
    The Properties window closes.

Related Topics

About the Web Service Activity | Selecting the Web Service and Method | Using Authentication to Access a Web Service | Storing the Web Service Output Parameters


Selecting the Web Service and Method

Before you can define the values you want to provide for a Web service's input parameters and select the Data Items you want store the Web service's output, you need provide the location of the Web service WSDL and select the method you want to invoke.

To Select the Web Service and Method

  1. Add the Web Service Invoker activity to the Canvas and complete the common activity properties.

  2. Click the Web Service tab.
    The URL Location and Web Method Selection sub-tab is in front.

  3. Click the WSDL Location box and enter the address of the Web service.

    Note
    The Web service address you enter here must be available now, while you configure the activity. If you want to use a different address for the Web service when the process runs, you can select it using the steps below.

  4. Click Go to retrieve a list of available methods.

  5. Click the Select Method to Invoke drop-down list and select the method you want to use.

  6. If the Web service address you entered in the WSDL Location box will not be accessible when the process runs, then select the Dynamic URL option.

  7. Enter the dynamic URL.

  8. If necessary, you can use authentication to access a Web service that requires authentication.

  9. Click the Input Parameters sub-tab and provide values for the input parameters.

  10. Click the Output Parameters sub-tab and set up how you want to store the Web service output parameters.

  11. Click OK.
    The Properties window closes.

Related Topics

About the Web Service Activity | Using Authentication to Access a Web Service | Providing Values for the Input Parameters | Storing the Web Service Output Parameters


Storing the Web Service Output Parameters

  1. Click the Filename cell in the same row. An ellipsis button appears.

  2. Click the ellipsis button. A window that allows you to create a unique file name appears.

  3. Enter the file name in the large text box.

  4. Optionally, click the Available Data Items drop-down list and select a Data Item to form part of the file name.

    Note
    You can select Display Value or Value, located at the right side of the window, to define which part of the Data Item you want to use.

  5. Optionally, click the Available Non-Data Items drop-down list and select a unique value, such as the date and time, to form another part of the file name.

  6. If you used Data Items or non-Data Item Values, then you can enter possible values for those variables in the Populate Variables to Test Expression grid. Then click Test Expression to see what the file name would look like.

  7. Click OK when you are done creating a unique file name.

Storing the Web Service Output Parameters

After you provide the address to the Web service you want to use and select the method, you can select Data Items that will hold the values that the Web service returns.

To Store the Web Service Output

  1. If you have not already done so, select the Web service and method you want to invoke.

  2. If necessary, you can use authentication to access a Web service that requires authentication.

  3. Click the Output Parameters sub-tab.

  4. Locate a parameter whose output you want to store in a Data Item.

  5. Click the Data Item cell in the same row and select a Data Item to store the return value.

    Note
    If you select a Data Item for a parameter that has other parameters beneath it, the Data item will contain the return values for all of the sub-parameters and those parameters will become unavailable.

    Note
    If you expect that the parameter will return a large amount of data, you should use a FilePointer Data Item to save the results. If the Data Item you select is a FilePointer Data Item, then you will need to create a name for the resulting file.

  6. Repeat steps 4-5 as necessary to set more Data Items to receive the output of the Web service.

  7. Click OK.
    The Properties window closes.

Related Topics

About the Web Service Activity | Selecting the Web Service and Method | Using Authentication to Access a Web Service | Providing Values for the Input Parameters


Using Authentication to Access a Web Service

If you want to use a Web service that requires authentication, you can enter a user name and password in the Web Service activity.

To Use Authentication to Access a Web Service

  1. If you have not already done so, select the Web service and method you want to invoke.

  2. Select the Enable Authentication option.

  3. Enter a user name through one of the following methods:

    • Choose the Select Data Item option, then click the drop-down list to select the Data Item that will contain the user name.

    • Choose the Enter value option, then click the box and enter the user name.

  4. Enter a password through one of the following methods:

    • Choose the Select Data Item option, then click the drop-down list to select the Data Item that will contain the password.

    • Choose the Enter value option, then click the box and enter the password.

  5. Click the Input Parameters sub-tab and provide values for the input parameters.

  6. Click the Output Parameters sub-tab and set up how you want to store the Web service output parameters.

  7. Click OK.
    The Properties window closes.

Related Topics

About the Web Service Activity | Selecting the Web Service and Method | Providing Values for the Input Parameters | Storing the Web Service Output Parameters


About the Web Service Invoker Activity

About the Web Service (v4.4) Activity

Important

This activity has been deprecated by a newer Web Service activity that supports complex Web services. This activity is still available in the Toolbox to maintain compatibility with previous implementations of BPM Suite that already use the activity. However, if you want to use a Web service, it is recommended that you use the newer Web Service activity or the Web Service Invoker Wizard.

You can use the Web Service Invoker activity to request information from and send information to a Web service.

Note:

The Web Service Invoker does not support Web services that use complex data types (such as Object) for an Input or Output.

To create a Web service activity template

The easiest way to set up a connection to a Web service is to use the Add/Edit Web Service Invoker Wizard. The Wizard allows someone with Web services knowledge to configure a template Web service connection. Process designers can then use the template connection and add only the information they need to send to and receive from the Web service. Use the following guide to help you configure the Add/Edit Web Service Invoker Wizard:

  • Configuring the Web Service Invoker Wizard

  • Using the Web Service Activity template

To configure the normal Web Service Invoker activity

You can use the following two types of web services with the Web Service Invoker activity:

  • Invoking a Public Web Service

  • Invoking a Secure Web Service

Required Auxiliary Topics

Before you begin configuring a Web Service Invoker activity, make sure to complete the following:

  • Create Data Items to store the Web service's inputs and outputs


Invoking a Public Web Service

A public web service is a web service that does not require authentication to use.

Note:

The Web Service Invoker does not support Web services that use complex data types (such as Object) for an Input or Output.

To invoke a public web service

  1. Add the Web Service Invoker activity to the Canvas and complete the common activity properties.

  2. Click the Web Service Invoker tab.

  3. Enter the URL of the Web Service in the Enter the URL Location for the Web Service field, by entering the Web Server's IP address or name, followed by the name of the Web Service file.

    Example:
    http://<bpm-server>/bluespring.webservices/workflow.asmx

  4. Click the Read Def button.
    The URL you typed is verified and a list of available methods populates the Select Method to Invoke drop-down list.

    Note:
    If the Web service URL is not valid, a URL Error window will appear, prompting you to verify the address.

  5. Click the Select Method to Invoke drop-down list and select the method you want this activity to execute.
    A table of parameters appears in the Parameters section.

    Note:
    For each parameter (i.e. piece of information used in the web service) the table will display the parameter name, the data type of the parameter, and whether it is an input or output. These fields are read-only. The table also has a column for you to assign a Data Item for each parameter. You can also define a File Name when the parameter is an output and the Data Item is a FilePointer.

  6. Click a field under the Data Item column and use the drop-down list to select a Data Item to store the input and output data for each parameter in the table.

  7. Click OK.
    The Properties for Activity window closes.

Related Topics

About the Web Service (v4.4) Activity


Invoking a Secure Web Service

Using a Secure Web Service

A secure Web service is a proprietary Web service that requires you to enter a user name and password in order to access it. A secure Web service may also run from a proxy server, requiring proxy server information in addition to the user name and password.

Note:
If you use a Secure Web Service, you must enter the Service Properties information (located at the bottom of the Web Service Invoker tab) before trying to read the available definitions from the web service.

Note:

The Web Service Invoker does not support Web services that use complex data types (such as Object) for an Input or Output.

To use a secure Web service

  1. Add the Web Service Invoker activity to the Canvas and complete the common activity properties.

  2. Click the Web Service Invoker tab.

  3. Enter the URL of the Web Service in the Enter the URL Location for the Web Service field, by entering the Web Server's IP address or name, followed by the name of the Web Service file.

    Example:
    http://<bpm-server>/bluespring.webservices/workflow.asmx

  4. Click the Read Def button.
    The URL you typed is verified and a list of available methods populates the Select Method to Invoke drop-down list.

    Note:
    If the web service URL is invalid, a URL Error appears, prompting you to verify the address.

  5. Enter the Service Properties for the secure web service according to the following table:

    For the

    Do the following

    User Name

    Optional: If this service requires authentication, then enter the User Name with permissions to access the Web Service.

    User Password

    In the User Password field, enter the password for the user name above.

    Service Time Out

    In the Service Time Out field, enter the amount of time to wait before timing out. By default, the time out value is set to 60.

    Note:
    If you delete the value and leave it blank and close this activity, the value will return to 60 when you reopen the activity.

Note:
If you need to access a Proxy Server, you will need to enter additional information.

  5. Click the Select Method to Invoke drop-down list and select the method you want this activity to execute.
    A table of parameters appears in the Parameters section.

    Note:
    For each parameter (i.e. piece of information used in the web service) the table will display the parameter name, the data type of the parameter, and whether it is an input or output. These fields are read-only. The table also has a column for you to assign a Data Item for each parameter. You can also define a File Name when the parameter is an output and the Data Item is a FilePointer.

  6. Click a field under the Data Item column and use the drop-down list to select a Data Item to store the input and output data for each parameter in the table.

  7. Click OK.
    The Properties for Activity window closes.

Related Topics

About the Web Service (v4.4) Activity


Web Service - Proxy Instructions

For the | Do the following
Use Proxy Server | If a Proxy Server is being used to access the Web Service, then select True from the Use Proxy Server drop-down list.
Proxy Server | Enter the name of the Proxy Server in the Proxy Server field.
Proxy Port | Enter the port number used by the Proxy Server in the Proxy Port field. The default Proxy Server port is 1080.
Proxy User Name | Enter the user name used to access the Proxy Server. Note: This user name could be different than the user name you use to log in to BPM Suite or the Web Service.
Proxy User Password | Enter the password for authorized proxy user name.


About the Web Service Invoker Wizard

You can use the Web Service Invoker Wizard to create a template activity that can easily call a specific Web service. You do not need to use the Web Service Invoker Wizard in order to use a Web service. If you feel comfortable working with Web services, you should probably use the Web Service activity.

Because some Web services are particularly complicated, and because it may be more efficient to create an activity that is tailored for a specific Web service, you may find it is easier to use the Web Service Invoker Wizard to create a custom activity that makes it easy to configure and use a Web service. You might want to have a Web Services Developer, or another expert in Web services, use the Web Service Invoker Wizard to create a template activity that you can use.

To Create a Custom Web Service Activity

  • Using the Web Service Invoker Wizard

To Configure the Custom Web Service Activity

  • Configuring a Custom Web Service Activity


Configuring a Custom Web Service Activity

  1. Click the Filename cell in the same row. An ellipsis button appears.

  2. Click the ellipsis button. A window that allows you to create a unique file name appears.

  3. Enter the file name in the large text box.

  4. Optionally, click the Available Data Items drop-down list and select a Data Item to form part of the file name.

    Note
    You can select Display Value or Value, located at the right side of the window, to define which part of the Data Item you want to use.

  5. Optionally, click the Available Non-Data Items drop-down list and select a unique value, such as the date and time, to form another part of the file name.

  6. If you used Data Items or non-Data Item Values, then you can enter possible values for those variables in the Populate Variables to Test Expression grid. Then click Test Expression to see what the file name would look like.

  7. Click OK when you are done creating a unique file name.

Configuring a Custom Web Service Activity

If someone in your organization uses the Web Service Invoker Wizard, then the result is a custom Web service activity. The custom Web service activity is designed to make it easy to use a specific Web service. You only need to define input and output parameters for the Web service.

When using the Web Service Invoker Wizard, it is possible to create "friendly names" for the parameters in a Web service. For that reason, the Parameter names you see in this activity might not be the actual names of the parameters.

By default, parameter names are prefaced with dashes to indicate hierarchy (e.g. one dash indicates the parameter is beneath one other parameter, two dashes indicates it is beneath two layers of other parameters).

To use a Custom Web Service Activity

  1. Add the Web Service Activity template to the Canvas and complete the common activity properties.

  2. Click the Web Service tab.
    The Input Parameters sub-tab is in front. A grid displays every available input parameter in the Web service.

    Note
    This activity may not show every input parameter in the Web service and the parameter names may have been changed, depending on how the Web Service Invoker Wizard that created this activity was used.

  3. Locate a parameter for which you need to set a value.

  4. Click the Source cell in the same row and select one of the following options:

    • Data Item Display Value - Select this option if you want to use the Display Value of a Data Item for the parameter.

    • Data Item Value - Select this option if you want to use the Value of a Data Item for the parameter.

    • Constant - Select this option if you want to use a static string of text for the parameter.

  5. Click the Value cell in the same row and perform one of the following actions:

    • If you selected Display Value or Value, then click the cell and use the drop-down list to select a Data Item.

    • If you selected Constant, then enter a string of text and/or numbers.

  6. Repeat steps 3-5 as necessary to set more values for input parameters.

  7. Click the Output Parameters sub-tab.
    A grid displays every available output parameter in the Web service.

    Note
    This activity may not show every output parameter in the Web service and the parameter names may have been changed, depending on how the Web Service Invoker Wizard that created this activity was used.

  8. Locate a parameter whose return value you need to record.

  9. Click the Data Item cell in the same row and select a Data Item to store the return value.

    Note
    If you select a Data Item for a parameter that has other parameters beneath it, the Data item will contain the return values for all of the sub-parameters and those parameters will become unavailable.

    Note
    If you expect that the parameter will return a large amount of data, you should use a FilePointer Data Item to save the results. If the Data Item you select is a FilePointer Data Item, then you will need to create a name for the resulting file.

  10. Repeat steps 8-9 as necessary to set more Data Items to receive the output of the Web service.

  11. Click OK
    The Properties window closes.


Using the Web Service Invoker Wizard

Using the Web Service Activity Wizard

The Web Service Activity Wizard allows someone with Web services knowledge to set up a connection to a Web service. That connection becomes a template for a Web Service Invoker activity. Process designers can use the template to send and receive information from a Web service without knowing how to configure the connection.

Note:

The Web Service Invoker does not support Web services that use complex data types (such as Object) for an Input or Output.

To use the Web Service Activity Wizard

  1. Right-click the background of the Toolbox (for example, in the gray area beneath the Web Service Invoker) and select Add Web Service. The Add/Edit Web Service Invoker Wizard appears.

  2. Click Next.

  3. Enter the URL of the WSDL that describes the Web service in the Enter the Web Service URL field. You should format the URL as in the example below (e.g. the Web Server's IP address or name followed by the name of the Web service file).

    Example:
    http://<bpm-server>/bluespring.webservices/workflow.asmx

  4. Click Next.

  5. Select whether the Web service requires a user name and password:

    • No - The Web service does not require authentication (no user name and password)

    • Yes - The Web service does require authentication (a user name and password)

  6. If you selected Yes, then use the User name and Password fields to enter the user name and password.

  7. Click Next.

  8. Select a Web service method to invoke.

  9. Click Next.
    The wizard displays a grid of every input parameter's name and type.

  10. Optionally, locate an input value whose name might be difficult to understand. Click the Friendly Name cell in the same row and enter an alternate name that will be easier to understand.
    Repeat this step for as many input parameters as necessary.

    Note
    The default parameter name may be prefaced with dashes to communicate the hierarchy of a parameter (e.g. one dash indicates the parameter is beneath one other parameter, two dashes indicates it is beneath two layers of other parameters). You may want to preserve the dashes in order to communicate the hierarchy of the information through the custom activity that this wizard creates.

  11. Optionally, locate an input parameter whose value you can set to a default. Click the Default cell in the same row and enter a default value.
    Repeat this step for as many input parameters as necessary.

    Note
    You can override a default value when you configure the final template activity.

  12. Optionally, locate an input parameter that does not need to be available in order to use the Web service. Select the Hide option in the same row to make that parameter invisible in the final template activity.
    Repeat this step for as many input parameters as necessary.

  13. Click Next.
    The wizard displays a grid of every output parameter's name and type.

  14. Optionally, locate an output parameter whose name might be difficult to understand. Click the Friendly Name cell in the same row and enter an alternate name that will be easier to understand.
    Repeat this step for as many input parameters as necessary.

  15. Click Next.

  16. Enter a name for the Web service template.

  17. Enter the name of a category that will contain the template. If the category name you enter is the same as an existing Toolbox category (e.g. Web Activities), the template will be located in that category. You can also put the template in a new category by entering a new category name.

  18. Enter a description of the Web service template. The description will appear as a tooltip when the mouse pauses over the activity.

  19. Optionally, click Select an Icon to give the Web service template a distinctive appearance.

  20. Click Next.

  21. Click Finish. The Web service template appears in the Toolbox category you defined


CAP - Web Activities

  1. Click the Web Activities category in the Toolbox.

  2. Double-click the activity you want to add, or drag it to the Canvas.
    The activity is added to the process.

  3. Open the Properties for the activity (double-click the activity or right-click and select Activity Properties).
    The Properties window appears.

  4. Complete the common activity properties.


Entering WebDAV Authentication Credentials

Before you can use any of the WebDAV activities, you need to enter WebDAV authentication credentials or specify that the activity use the BPM engine credentials. Credentials include a username, password. If necessary, you can include a domain as well. You can either enter these values when you configure the activity, or you can select Data Items that will contain the values when the process runs.

To enter WebDAV authentication credentials

  1. Add one of the WebDAV activities to the Canvas and complete the common activity properties.

  2. Click the WebDAV tab.

  3. In the WebDAV tab, click the WebDAV Authentication Credentials sub-tab.

  4. Choose the credentials you whish to use:

    • Choose the Use BPM Engine Credentials option, or

    • Choose the Specify Credentials option to specify different credentials

      1. In the "WebDAV username" section:

        • To provide the username as a Data Item, click the Select Data Item option, click the drop-down list, and select the Data Item that will contain the username.

        • To enter the username now, click the Enter value option and enter the username in the box.

      2. In the "WebDAV password" section:

        • To provide the password as a Data Item, click the Select Data Item option, click the drop-down list, and select the Data Item that will contain the password.

        • To enter the password now, click the Enter value option and enter the password in the box.

      3. If your WebDAV repository is in a domain, then select the WebDAV domain checkbox and continue to step 3. Otherwise, skip to step 5.

      4. In the "WebDAV domain" section:

        • To provide the domain as a Data Item, click the Select Data Item option, click the drop-down list, and select the Data Item that will contain the domain name.

        • To enter the domain name now, click the Enter value option and enter the domain name in the box.

  5. If you need to use a Secure Sockets Layer (SSL) connection to connect to your WebDAV repository, then select the Use SSL option.

You can now continue following the steps in the WebDAV Copy or Move File Activity, WebDAV Delete Activity, WebDAV Get File Activity, WebDAV Get File Structure Activity, or WebDAV Put File Activity.

Related Topics

About the WebDAV Delete File Activity | About the WebDAV Get File Activity | About the WebDAV Get File Structure Activity | About the WebDAV Put File Activity


Folder Locations - Web Activities

  • If the Data Item points to a file and has a Data Type of FilePointer, then the file needs to be located in the following folder within the Repository:

    Files\<database server name or IP>\<database name>\<site>\<Data Item name>

  • If the Data Item points to a file and does not have a Data Type of FilePointer, then the file needs to be located in the following folder within the Repository:

    Workflow\Documents\<database server name or IP>\<database name>\<site>\<Group ID>\<Workflow ID>

  • If the process is within a sub-process, then there will be multiple Workflow IDs separated by backslashes ( \ ). You can also set this file path earlier in the process so it points to a different file location.


About the Document Generator Activity

You can use the Document Generator activity to manipulate and display XML in a report-like structure. You can export Document Generator files in a number of formats including Rich Text Format (RTF) and Portable Document Format (PDF). The PDF option does not require you to have an application or engine installed on the server that can convert documents to PDF.

Important:
Since this task allows you to use XML as the input for your document, this activity is usually accompanied by at least one Query By Example activity in your process before this Document Generator activity. For one, the Document Generator activity needs to use Sample XML created by the Query By Example activity. If you have multiple Query By Example activities, you can merge the resulting XML from those activities by using the Merge XML activity.

However, you may have an XML document that you retrieve from another activity in your process. This XML document can also be used when the process runs. You will use a copy of this XML document to design your document.

  • Cre ating Document Layouts

  • Using the Document Generator window

  • Creating a Document with Process Information

Required Auxiliary Topics

Before you can properly configure a Document Generator activity, you must create Data Items that store the names of the input and output documents and any sample XML that you may need.

  • Setting the output file name

  • Creating Data Items


Creating a Document with Process Information

The Document Generator activity allows you automatically create documents based on XML input and Data Item input.

To creating a Document with Process Information

  1. Add the Document Generator activity to the designer canvas and complete the common activity properties.

  2. Click the Document Generator tab.

  3. Click the Data Item for Input Document drop-down list and select the Data Item that will hold the input XML document to use when the process runs.

  4. Click the Data Item for Output Document drop-down list and select the Data Item that will hold the document after it has been created in the process.

  5. Click the Select Sample XML drop-down list and select the activity with the sample XML you want to use when designing your document or select [Load From File] to load a file to use when designing your document.

    Note:
    You will be prompted for the XML file when you click the Edit the Currently Assigned Document Layout button.

  6. Click the At Run-Time, Save the finished document in this format drop-down list, select the format in which you want to output the document.

  7. Click the ellipses button to the right of the At Run-Time, Save the finished document in this format drop-down list.
    The window that opens allows you to set the output file name.

    Tip:
    To make files unique, you can use the Group ID Data Item in the file name.

  8. From the Available Document Layouts list, double-click the document layout you want to use with this activity.

    Important:
    If you change the way an existing document looks in this activity, every other Document Generator activity that uses this same document layout will also be updated.

    Note:
    You can create a new layout to fit your needs.

  9. Click the Edit Currently Assigned Document Layout button [image] to configure the document's design.

  10. Click OK. The Properties window closes.

Related topics

About the Document Designer Activity


Creating Document Layouts

When you add a Document Generator activity to your process, you can use a Document Layout to control the way XML data is presented and what data is used. If the layout you want to use does not exist, you can create one.

Note:
If a similar layout to the one you want to create exists, you may want to edit the existing layout rather than create a new one. Updating a similar layout and saving it under a new name will save you time.

To create a document layout

  1. Click the Create a New Document Layout button.
    The Document Layout Properties window appears.

  2. Enter the name of the new layout in the Layout Name box.

  3. Select a category from the Layout Category list.

    Note:
    To add a category, update the Sys_WorkflowCategory list by accessing it via List Management.

  4. If necessary, enter the an additional category in which to place this layout in the Layout Path box.

    Example:
    If the Layout Category is Documents and the Layout Path is Partner One, then the layout will appear in the Partner One folder within the Documents folder.

    Note:
    The Layout Category and Layout Path act similar to the process Category and Display Path, respectively.

  5. Click OK.
    The Document Layout Properties window closes.

    Now you can design the assigned document's layout.

Related topics

About the Document Generator Activity


Using the Document Generator Window

When you use the Document Generator activity, you can choose a design to apply to your process's XML data. If the design you want does not exist, you can create a new document design.

Note:

You can use this topic to develop an understanding of the Document Generator window. This topic does not explain the process of creating a new design.

For additional help on using the Document Generator, please refer to Data Dynamics Web site: http://www.datadynamics.com/Help/AR2Std/AR2Std_start.htm

To use the Document Generator window

  1. After you create or select a document layout to use, click the Edit the Currently Assigned Document Layout button.
    The Document Generator window appears.

  2. The Document Generator window is divided into the following major sections:

    Section

    Function

    Design

    The Design section displays a grid for you to design your document visually using the elements in the Toolbox.

    Sample XML

    The Sample XML section shows what the XML that will be used to create your document looks like. The Sample XML is displayed in the bottom half of the Document Generator window.

  3. When you are finished designing the document, click OK.

Related topics

About the Document Generator Activity


About the Merge XML Documents Activity

You can use the Merge XML Documents activity to merge two XML documents into one XML document. You can store the generated XML document as a large, complete XML file or, if it is small, you can store the entire XML document in a Data Item.

Follow the four links below to learn how to configure the Merge XML Documents activity.

  • Configuring Merge XML Conditions

  • Merging XML Documents into an XML File

  • Merging XML Documents into a Data Item

  • Generating Sample XML Data

Required Auxiliary Topics

Before you can completely configure a Merge XML Documents activity, you need to create a Data Item that will either store the file name or entire file of the outputted XML document.

  • Creating Data Items

  • Creating a FilePointer Data Item


Configuring Merge XML Conditions

When using a Merge XML Documents activity, you need to configure the merge conditions before generating any sample XML data. Configuring the merge conditions allows you to define how the data in two XML documents will combine to make a new XML document.

To configure the merge XML conditions

  1. When adding a Merge XML Documents task, click the Configure Merge Conditions button on the Merge XML tab.
    The XML Merge Configuration window opens.

  2. Using the Document #1 drop-down list, select the activity with the sample XML document you want to use.
    The activity's XML appears hierarchically in the box below the list.

    Note:
    You can also load sample XML from a task outside this process by selecting the Load from file option.

  3. Using the Document #2 drop-down list, select the activity with the sample XML document you want to use.
    The activity's XML appears hierarchically in the box below the list.

  4. Select an XML node from both the Document #1 and Document #2 XML lists.
    These are the nodes you want to compare and if any match, you will output the information.

    Note:
    Selected nodes to be compared appear in the Merge Keys list.

  5. Click the Equal button.
    These nodes will be compared for matches when this Merge XML Documents activity executes.

    Note:
    You can repeat steps 4 and 5 until you select all the nodes you want to compare.

  6. Click OK.
    The XML Merge Configuration window closes.

Related topics

About the Merge XML Documents Activity


Merge XML Documents into an XML File

Merging XML Documents into an XML File

Using the Merge XML Documents activity, you can merge two XML documents into a single XML document.

Note:

When merging XML, you will need two Data Items from which to obtain information from the XML documents.

To merge XML documents into a XML file

  1. Add the Query by Example activity to the designer canvas and complete the common activity properties.

    Note:
    Completing common activity properties is essential to create an organized and functional process.

  2. Click the Merge XML tab.

  3. Using the Data Item for Document #1 drop-down list, select a Data Item that stores a result from a Query by Example activity.

  4. Using the Data Item for Document #2 drop-down list, select a different Data Item that stores a result from a different Query by Example activity.

  5. Under the Output Document - > Parent XML tag, click the radio button with the parent XML tag option you want to use in the merged document.

    Note:
    If you choose Specify XML tag, then type the name of the XML tag you want to use in the corresponding box.

  6. Under the Output Document - > Child XML tag, click the radio button with the child XML tag option you want to use in the merged document.

    Note:
    If you choose Specify XML tag, then type the name of the XML tag you want to use in the corresponding box.

  7. Under Where should the output xml be sent, click the File, Save File Path in Data Item checkbox.

  8. Using the drop-down list, select a Data Item to store the file name of the XML document.

    Note:
    You can use Data Items to name the file by clicking the ellipses button and selecting Data Items in the window that appears. Click the Test Expression button to view the resulting file name.

  9. Configure the merge conditions.
    The conditions you specify will determine how the merged XML document is produced.

  10. Generate sample XML data.
    Generating sample XML data allows you to view the XML that will this activity will produce, allowing you to verify that it is correct.

  11. Click OK.
    The Properties for Activity window closes.

Related topics

About the Merge XML Documents Activity


Merging XML Documents into a Data Item

You can use the Merge XML Documents activity to merge two XML documents into a Data Item, as long as the resulting merged document is small enough to fit into a Data Item.

If the merge XML documents will create a large file, merge them into an XML file instead.

Note:

When merging XML, you will need two Data Items from which to obtain information from the XML documents.

To merge XML documents into a Data Item

  1. Add the Query by Example activity to the designer canvas and complete the common activity properties.

    Note:
    Completing common activity properties is essential to create an organized and functional process.

  2. Click the Merge XML tab.

  3. From the Data Item for Document #1 drop-down list, select a Data Item that stores a result from a Query by Example activity.

  4. From the Data Item for Document #2 drop-down list, select a different Data Item that stores a result from a different Query by Example activity.

  5. Under the Output Document - > Parent XML tag, click the radio button with the parent XML tag option you want to use in the merged document.

    Note:
    If you choose Specify XML tag, then type the name of the XML tag you want to use in the corresponding box.

  6. Under the Output Document - > Child XML tag, click the radio button with the child XML tag option you want to use in the merged document.

    Note:
    If you choose Specify XML tag, then type the name of the XML tag you want to use in the corresponding box.

  7. Under Where should the output xml be sent, click the Data Item checkbox.

  8. Select a Data Item from the drop-down list to store the XML outputs from this activity.

  9. Configure the merge conditions.
    The conditions you specify will determine how the merged XML document is produced.

  10. Generate sample XML data.
    Generating sample XML data allows you to view the XML that will this activity will produce, allowing you to verify that it is correct.

  11. Click OK.
    The Properties for Activity window closes.

When the activity executes, it will store the entire resulting XML document in the Data Item you selected in step 8.


About the Query by Example Activity

The primary use of the Query by Example activity is to retrieve information from a database table so that you can use it in either a Document Designer or Merge XML activity.

Follow the link below to learn how to configure the Query by Example activity.

  • Retrieving Data from a Database to Use in an XML Document

Before you execute a process with a Query by Example activity, you can generate sample XML that will result from the activity in order to verify that you query is correct.

  • Generating sample XML data

Defining SQL Queries in the Query by Example Activity

You can auto-define or manually define database queries in a Query by Example activity.

  • Automatically Define a SQL Query

  • Manually Define a SQL Query

Required Auxiliary Topics

To properly configure a Query by Example activity, you need to create Data Items that store the parameters for your query and that will store the result of your query.

  • Creating Data Items


Automatically Define a SQL Query

When you configure a Query by Example activity, you can automatically define SQL queries using the Query Design tab.

Note:
You can write your own SQL query on the 3. Advanced (optional) tab, instead of using the Query Window. If you write a SQL query, you will not be able to edit it using the Query Window.

To automatically define a SQL query

  1. When configuring a Query by Example activity, click the 2. Query Design tab on the Query by Example tab.

  2. If you want to use the display value in the results, click the Use Display Value in results checkbox.

  3. Click the Define Query button.
    The Query Window opens.

  4. Drag tables from the Browser section to the empty gray pane under the Design Query tab.
    A window appears for each table in the gray pane that displays their column values.
    The name of each table you drag to the pane under the Design Query tab appears under the FROM part of the statement.

  5. For each table window under the Design Query tab, click the checkboxes next to the column names you want to include in your query.
    The name of each column appears under the SELECT part of the statement and in the table in the middle of the window.

    Note:
    You can use this table to define options for each column name you selected from the tables.

  6. When you are finished, close the Query Window.
    Your SQL query is defined.

    Now you can generate sample XML data.

Related topics

Generating sample XML data


Generating Sample XML Data

You can generate sample XML data when configuring Query by Example activities and Merge XML Documents activities in order to view the results of these activities before they execute in a process.

Before you generate sample XML data for a Query by Example activity, you need to define the SQL query. Before you generate sample XML data for a Merge XML activity, you need to configure the merge conditions.

To generate sample XML data for a Query by Example activity

  1. Define the SQL query

  2. Click the 4. Sample XML sub-tab under the Query By Example tab.

  3. Click the Generate Sample XML button.
    Sample XML data appears in the box. You can use this XML later with the Merge XML Documents task and the Document Designer task.

    Note:
    If you need to enter values for Data Items, places the values in single quotes. Although quotes are necessary for the Sample XML generator, they are not necessary at run-time.

To generate sample XML data for a Merge XML activity

  1. After configuring the merge conditions, click the Generate Sample Data button on the Merge XML tab.
    A window opens with the sample XML data displayed. You can use this sample XML with the Document Designer task.

  2. Review the sample XML, and then click OK.

    Note:
    If you're not satisfied with the sample XML, click Cancel and configure the merge conditions again.

Related topics

Configuring merge XML conditions


Manually Define a SQL Query

If you have extensive SQL statement experience, then you can manually code the query to retrieve data for an XML document by using the advanced tab in the Query by Example activity.

To manually define a SQL query

  1. When configuring a Query by Example activity, click the 3. Advanced sub-tab on the Query by Example tab.

  2. Click the Manipulate QBE Query button.
    The field below the Manipulate QBE Query button is enabled.
    The field in the 2. Query Design tab is disabled.

  3. Enter your database query in the field under the Manipulate QBE Query button.

    Note:
    If you include Data Items as part of your query, do not put single or double quotes around them. When the activity runs, single quotes are automatically added.

  4. View the results by clicking the Generate Sample XML button on the 4. Sample XML tab.

Related Topics

About the Query by Example Activity


Retrieving Data from a Database to Use in an XML Document

You can use a Query by Example activity to retrieve information from a database that you want to output as XML later on in the process. This task is used before a Merge XML activity or Document Generator activity.

Note:
You will need to understand the structure of the database you will query and know how to write SQL statements in order to configure this activity.

To configure a Query by Example activity

  1. Add the Query by Example activity to the designer canvas and complete the common activity properties.

    Note:
    Completing common activity properties is essential to create an organized and functional process.

  2. Click the Query By Example tab.

  3. From the list of Data Items to use as parameters in the query on the 1. Connection/Data Items tab, select a Data Item you want to use.

  4. Click the > button.
    This Data Item will be available for your query.

    Note:
    Repeat steps 3-4 to include more Data Items as parameters in your query.

  5. From the Data Item to hold result drop-down list, select the Data Item that you want to store the information retrieved by your database query.

  6. Click the ellipses button and set the name of the output XML file.

  7. Click the Database to query list, and then select a database to query.
    This database will be the one from which you gather your results.

    Note:
    If you select the Non-PCS option, then you have to configure the database connection string on the 3. Advanced (optional) tab.

  8. Click the 2. Query Design tab.
    On this tab, you can view your SQL query after defining it.

  9. Click the Define Query button.
    The Query Window opens.

  10. Define your SQL query and close the window.

  11. Click OK.
    The Properties for Activity window closes.

    You are ready to create a document with process information.


Setting the Name of the XML Output File

To configure the Query by Example activity, you must set a name for the XML output file. When you set the output file name, you can also decide if this activity will overwrite existing files with the same name or create a new file with an incremental number appended to the end.

To set the name of the XML output file:

  1. Click the ellipses button next to the Data Item to hold result drop-down list.
    The Query By Example window appears.

  2. Enter a file name in the large blank field.

  3. To include Data Items in your file name:

  • Select the option to display a Data Item's value or display value.

  • Select the Data Item you want to include from the drop-down lists.
    The Data Items display value or value (depending on your choice) appears in the large field with percent signs around it.

    The percent signs mean the Data Item will be replaced by the value stored by the Data Item when the file is saved.

    Example:
    %FlowName.DisplayValue%_%WorkflowID.Value%_%TaskName.DisplayValue%_%TimeStamp.Value%

    Note:
    The .xml file extension will be added automatically.

  4. Select the Append Unique String to Name option if you want to ensure that the XML file this activity creates does not overwrite any existing files with the same name.
    If you select this option, and another file with the same name already exists, the activity will append a number to the new file's name.

    Example    : If the folder already contains a file named file.xml, this activity will create a file named file-1.xml.
    Note:     You can also give the files unique names by adding Data Items such as Timestamp or GroupID.

  5. To test a file name that uses Data Items:

  • Enter the expected values of the Data Items in the Populate Variable to Test Expression table.

  • Click the Test Expression button.
    The resulting file name appears in the Expression Results field.


About the XML Reader Activity

You can use the XML Reader to populate Data Items by running an XPath Query against XML stored in a file or in a Data Item.

Note:
You should be familiar with writing XPath Queries in order to properly configure the value.

There are two types of locations that the XML Reader can populate data from (either XML Files or XML Text within a Data Item). You can learn how to read XML from the locations by following the links below.

Reading Information from XML Files

  • Automatically Populating Data Items based on Information in an XML File Using an XPath Query

  • Manually Populating Data Items based on Information in an XML File Using an XPath Query

Reading Information from XML Text within a Data Item

  • Automatically Populating Data Items based on XML Text within a Data Item Using an XPath Query

  • Manually Populating Data Items based on XML Text within a Data Item Using an XPath Query

Required Auxiliary Topics

To store the information you read from XML text, you need to create Data Items for each piece of information that you will store.

  • Creating Data Items


Automatically Populating Data Items Based On Information in an XML File Using an XPath Query

You can use the XML Reader activity to populate Data Items with the results of an XPath query.

XML Reader can read information from XML files in an automatic or manual mode. The automatic mode replaces the element placeholder in your XPath Query with the XML tag of any Data Items that you choose (the XML tag of a Data Item is the Data Item name with any spaces removed).

For example, you might write the following XPath query:

//%DATAITEM%

Then the XML Reader automatically replaces the element placeholder (%DATAITEM%) with the XML tag of any selected Data Items, such as:

  • UserName

  • Email

  • PhoneNumber

As a result, the XML Reader would generate the following XPath queries:

  • //UserName

  • //Email

  • //PhoneNumber

Finally, the XML Reader writes the results of each XPath query to the appropriate Data Item (e.g., The //UserName query results are written to the UserName Data Item).

Note:
You should be familiar with writing XPath Queries in order to properly configure the value.

To automatically populate data items based on information in an XML file using an XPath query

  1. Add the XML Reader activity to the designer canvas and complete the common activity properties.

  2. Click the XML Reader tab.

  3. Click the File Pointer Data Item option, and then select the FilePointer Data Type Data Item that points to the XML file you want to use.

  4. Click the Automatic Data Item Mapping option.

  5. In the XPath Query field, enter your XPath Query.

    Note:
    Somewhere in your XPath Query, you will have to include %DATAITEM%, which will be replaced by the Data Items you select in step 9.

  6. Click the Insert Data Item Name button to insert %DATAITEM% into your query.

    Examples:
    %DATAITEM%
    //DataItem_%DATAITEM%

  7. Click the Update from specific XML attribute option to use a value attached to an attribute of the XML node or click the Update from XML element value option to use the value between the XML tags.

    Note:
    If you selected the Update from specific XML attribute option, enter the attribute from which you want the value to come in the Attribute Name field.

  8. Click the Select Data Items to Update button.
    A window opens with a list of available Data Items to update.

  9. Click the check box next to the Data Items you want to update automatically via the XPath Query and the XML source.

    Note:
    The Data Items you select here will replace the %DATAITEM% text in the XPath Query when it runs.

  10. When you are finished selecting Data Items to use, click OK to close the window.

  11. Click OK.
    The Properties for Activity window closes.

Related Topics

Understanding BPM Activities


Automatically Populating Data Items based on XML Text within a Data Item Using an XPath Query

Using the XML Reader, you can automatically populate Data Items by running an XPath Query against XML stored in a Data Item.

Note:
You should be familiar with writing XPath Queries in order to properly configure the value.

To use automatically populate Data Items based on XML text within a Data Item using an Xpath Query

  1. Add the XML Reader Activity to the designer canvas and complete the common activity properties.

  2. Click the XML Reader tab.

  3. Click the XML Text within a Data Item option, and then select the Data Item that contains the XML text you want to use.

  4. Click the Automatic Data Item Mapping option.

  5. In the XPath Query field, enter your XPath Query.

    Note:
    Somewhere in your XPath Query, you will have to include %DATAITEM%, which will be replaced by the Data Items you select in step 9.

  6. Click the Insert Data Item Name button to insert %DATAITEM% into your query.

    Examples:
    %DATAITEM%
    //DataItem_%DATAITEM%

  7. Click the Update from specific XML attribute option to use a value attached to an attribute of the XML node or click the Update from XML element value option to use the value between the XML tags.

    Note:
    If you selected the Update from specific XML attribute option, enter the attribute from which you want the value to come in the Attribute Name field.

  8. Click the Select Data Items to Update button.
    A window opens with a list of available Data Items to update.

  9. Click the check box next to the Data Items you want to update automatically via the XPath Query and the XML source.

    Note:
    The Data Items you select here will replace the %DATAITEM% text in the XPath Query when it runs.

  10. When you are finished selecting Data Items to use, click OK to close the window.

  11. Click OK.
    The Properties for Activity window closes.

Related Topics

About the XML Reader Activity


Manually Populating Data Items based on Information in an XML File Using an XPath Query

Using the XML Reader, you can manually populate Data Items by running an XPath Query against XML stored in a file.

Note:
You should be familiar with writing XPath Queries in order to properly configure the value.

To manually populate Data Items based on Information in an XML File Using an XPath Query

  1. Add the XML Reader Activity to the designer canvas and complete the common activity properties.

  2. Click the XML Reader tab.

  3. Click the File Pointer Data Item option, and then select the FilePointer Data Type Data Item that points to the XML file you want to use.

  4. Click the Manual Data Item Mapping option.
    A table with four columns appears and hides the information available for automatic Data Item mapping.

  5. In the Data Item column, select the Data Item you want to update.

  6. In the XPath Query column, enter your XPath Query to use to update this Data Item's value.

    Note:
    To access a default non-null namespace (for example, xmlns=http://example.com), you will have to use the "default" prefix in your xpath queries. The following query will work: //default:GetPermissionCollection/default:Permissions/default:Permission

  7. In the Value Location column, select Element Value to get the value between the XML tags or select Attribute Value to get a specific attribute value.

    Note:
    If you select Attribute value, enter the attribute from which you want the value to come in the Attribute Name column.

    Note:
    Repeat steps 2 through 4 here to add more manual Data Item mappings.

  8. Click OK.
    The Properties for Activity window closes.

Related Topics

About the XML Reader Activity


Manually Populating Data Items based on XML Text within a Data Item Using an XPath Query

Using the XML Reader, you can manually populate Data Items by running an XPath Query against XML stored in a Data Item.

Note:
You should be familiar with writing XPath Queries in order to properly configure the value.

To manually populate Data Items based on XML text within a Data Item using an XPath query

  1. Add the XML Reader Activity to the designer canvas and complete the common activity properties.

  2. Click the XML Reader tab.

  3. Click the XML Text within a Data Item option, and then select the Data Item that contains the XML text you want to use.

  4. Click the Manual Data Item Mapping option.
    A table with four columns appears and hides the information available for automatic Data Item mapping.

  5. In the Data Item column, select the Data Item you want to update.

  6. In the XPath Query column, enter your XPath Query to use to update this Data Item's value.

    Note:
    To access a default non-null namespace (for example, xmlns=http://example.com), you will have to use the "default" prefix in your xpath queries. The following query will work: //default:GetPermissionCollection/default:Permissions/default:Permission

  7. In the Value Location column, select Element Value to get the value between the XML tags or select Attribute Value to get a specific attribute value.

    Note:
    If you select Attribute value, enter the attribute from which you want the value to come in the Attribute Name column.

    Note:
    Repeat steps 2 through 4 here to add more manual Data Item mappings.

  8. Click OK.
    The Properties for Activity window closes.

Related Topics

About the XML Reader Activity


About the XML Writer Activity

You can use the XML Writer activity to create a new XML file or to update an existing XML file (through inserting, updating, or deleting existing elements). The activity is able to use a combination of XPath queries and Data Item values to create and modify XML. It can also create an XML file that contains information about every Data Item in the process at the time the activity is run. Finally, you can save the completed XML file to a Data Item or to a file (using a FilePointer Data Item).

To Select the XML File to Update

  • Creating a New XML File

  • Updating an Existing XML File

To Write or Update the XML

  • Inserting, Updating, or Deleting XML Elements

  • Writing All Data Item Values to XML

To Save the Output XML

  • Saving the Output XML to a Data Item

  • Saving the Output XML to a File

Required Auxiliary Topics

Before you can completely configure an XML Writer activity, you need to create Data Items that will store the values you want to write to the XML file. You may also need to create a FilePointer Data Item to store the output file.

  • Creating Data Items

  • Creating a FilePointer Data Item


Creating a New XML File

  1. Select the Version option to enable that pseudo-attribute.

  2. Enter the version number you want to associate with this XML file.

  1. Select the Encoding option to enable that pseudo-attribute.

  2. Enter the encoding format you plan to use in the field.

    Note
    Common encodings including UTF-8, UTF-16, and (in the Americas and Western Europe) LATIN-1.

  1. Select the Standalone option to enable that pseudo-attribute.

  2. Click the drop-down list and select either Yes or No.

    Note
    If you set the Standalone attribute to Yes, then you are indicating that the external subset of the DTD contains declarations that could affect the actual content of the document.

Creating a New XML File

The XML Writer activity can create a new XML file. When you create a new XML file, you probably want to include a declaration line that identifies the file as an XML document. This activity lets you insert a declaration line and determine which attributes it contains.

If you already have an XML file that you want to edit, please refer to the article about updating an existing XML file.

To Create a New XML File

  1. Add the XML Writer activity to the Canvas and complete the common activity properties.

  2. Click the XML Writer tab.
    The Input sub-tab is in front.

  3. Select the Create XML option.

  4. Specify a root XML element for the document through one of the following methods:

    • Choose the Enter root element name option and enter the root element as text.

    • Choose the Select Data Item option and click the drop-down list to select the Data Item that will contain the root element.

  5. Optionally, select the Include declaration option.

    Note
    An XML declaration is recommended for XML 1.0 and required for well-formatted XML 1.1.

  6. If you include a declaration, then you can set the Version, Encoding, and Standalone pseudo-attributes.

  7. Click the Output sub-tab and determine how you want to save the output XML file:

    • Saving the Output XML to a Data Item

    • Saving the Output XML to a File

  8. Click the Data Item Mapping sub-tab and update the XML document through one of the following methods:

    • Inserting, Updating, or Deleting XML Elements

    • Writing All Data Item Values to XML

  9. Click OK.
    The Properties window closes.


Inserting, Updating, or Deleting XML Elements

You can use the XML Writer activity to insert, update, or delete values from an XML file by writing XPath queries to identify the XML element that should be inserted, updated, or deleted. After you identify the XML element to modify, you can insert or update the element or you can insert or update an attribute for the element. Using this part of the XML Writer activity will require the ability to write XPath queries.

To Insert, Update, or Delete XML Elements

  1. If you have not already done so, use one of the following methods to select the XML file to update:

    • Creating a New XML File

    • Updating an Existing XML File

  2. If you have not already done so, click the Output sub-tab and determine how you want to save the output XML file:

    • Saving the Output XML to a Data Item

    • Saving the Output XML to a File

  3. Click the Data Item Mapping sub-tab.

  4. Select the Map Data Items to XML elements option.

  5. Click the Query cell in the first row and enter an XPath query to locate an XML element.

  6. Click the Action cell in the same row and select one of the following options:

    • Insert Element - Inserts a new element inside the element that the XPath query identifies

    • Insert Attribute - Inserts a new attribute for the element that the XPath query identifies

    • Update Name - Updates (overwrites) the name of the element that the XPath query identifies

    • Update Value - Updates (overwrites) the value of the element (not the value of any attribute)

    • Delete - Deletes the element that the XPath query identifies

  7. If you selected Delete, then you do not need to select any other values.

  8. If you selected any of the other four options, then click the Source cell in the same row and select one of the following options:

    • Display Name - Inserts or updates the element with the Display Name of the Data Item.

    • XML Tag - Inserts or updates the element with the XML Tag of the Data Item.

    • Display Value - Inserts or updates the element with the Display Value of the Data Item.

    • Value - Inserts or updates the element with the Value of the Data Item.

    • Constant - Inserts or updates the element with any string of text you enter now.

  9. If you selected Constant, then you should click the Data Item/Value cell and enter the string of text you want to use.

  10. If you selected any of the other four options, then click the Data Item/Value cell in the same row and select the Data Item you want to use to insert or update the element.

  11. Click OK
    The Properties window closes.


Saving the Output XML to a Data Item

You can use the XML Writer activity to save the completed XML file to a Data Item. In this case, you would be saving the entire text of the XML inside a Data Item, as opposed to using a FilePointer Data Item to save the text in a normal file visible in Windows.

If you want to save the output XML to a normal file using a FilePointer Data Item, please refer to the article about saving the output XML to a file.

To Save the Output XML to a Data Item

  1. If you have not already done so, use one of the following methods to select the XML file to update:

    • Creating a New XML File

    • Updating an Existing XML File

  2. Click the Output sub-tab.

  3. Select the Save output XML to Data Item option.

  4. Click the Data Item drop-down list and select the Data Item that you want to contain the output XML.

    Note
    UserID and FilePointer Data Items are not available in this list.

    Note
    Because of size limitations, the Data Item cannot store more than 2000 characters of XML. If you need to store more XML, you should save the output XML to a file.

  5. Click the Data Item Mapping sub-tab and update the XML document through one of the following methods:

    • Inserting, Updating, or Deleting XML Elements

    • Writing All Data Item Values to XML

  6. Click OK.
    The Properties window closes.


Saving the Output XML to a File

You can use the XML Writer activity to save the completed XML file to a File. In order to save to a file that is available in Windows, you need to select a FilePointer Data Item and provide a name for the file.

If you want to save the output XML to as plain text in a Data Item, please refer to the article about saving the output XML to a Data Item.

To Save the Output XML to a File

  1. If you have not already done so, use one of the following methods to select the XML file to update:

    • Creating a New XML File

    • Updating an Existing XML File

  2. Click the Output sub-tab.

  3. Select the Save output XML to file option.

  4. Click the Data Item drop-down list and select the FilePointer Data Item that you want to contain the output XML.

  5. Click the Edit button next to the Output file name box. A window that lets you design the file name appears.

  6. If you want to enter static text as the XML file name, then click the File name box and enter text.

  7. If you want to include Data Item values in the Excel file name, then select a Data Item in the Available Data Items list and click Insert Display Value or Insert Value.

    Note:     There may be a difference between the Value and the Display Value of a Data Item.

  8. If you want to include a non-Data Item value in the XML file name, then select one of the options in the Available Non-Data Items list and click Add.

    The File name field shows the final file name with placeholders for all the variables.

  9. Click the Preview File Name button to enter values for the variables and see what the final file name might look like.

  10. Click OK when you're done creating the output file name.

  11. The file name appears in the Output file name field.

  12. Select one of the following options to determine how you will handle the XML output file if another file with the same name already exists:

    • Select Overwrite the existing file if it exists to replace any existing file with the same with the new output file.

    • Select Increment file name if it exists to add an incremental number to the end of the file name (e.g. FileName-1.xml, FileName-2.xml).

  13. Click the Data Item Mapping sub-tab and update the XML document through one of the following methods:

    • Inserting, Updating, or Deleting XML Elements

    • Writing All Data Item Values to XML

  14. Click OK.
    The Properties window closes.


Updating an Existing XML File

  1. Select the Version option to enable that pseudo-attribute.

  2. Enter the version number you want to associate with this XML file.

  1. Select the Encoding option to enable that pseudo-attribute.

  2. Enter the encoding format you plan to use in the field.

    Note
    Common encodings including UTF-8, UTF-16, and (in the Americas and Western Europe) LATIN-1.

  1. Select the Standalone option to enable that pseudo-attribute.

  2. Click the drop-down list and select either Yes or No.

    Note
    If you set the Standalone attribute to Yes, then you are indicating that the external subset of the DTD contains declarations that could affect the actual content of the document.

Updating an Existing XML File

The XML Writer activity can update an existing XML file. When you update an existing XML file, you may want to change the declaration line. This activity lets you overwrite the declaration line with a new one.

If you want to create a new XML file, please refer to the article about creating a new XML file.

To Update an Existing XML File

  1. Add the XML Writer activity to the Canvas and complete the common activity properties.

  2. Click the XML Writer tab.
    The Input sub-tab is in front.

  3. Select the Update XML option.

  4. Click the Data Item drop-down list and select the FilePointer Data Item that will contain the XML file you want to update.

  5. Optionally, select the Include declaration option to overwrite the existing declaration line.

    Note
    An XML declaration is recommended for XML 1.0 and required for well-formatted XML 1.1.

  6. If you include a declaration, then you can set the Version, Encoding, and Standalone pseudo-attributes.

  7. Click the Output sub-tab and determine how you want to save the output XML file:

    • Saving the Output XML to a Data Item

    • Saving the Output XML to a File

  8. Click the Data Item Mapping sub-tab and update the XML document through one of the following methods:

    • Inserting, Updating, or Deleting XML Elements

    • Writing All Data Item Values to XML

  9. Click OK.
    The Properties window closes.


Writing All Data Item Values to XML

You can use the XML Writer activity to write the actual XML content of every Data Item in the process to an XML file. You can select any element in the XML file to contain the Data Item XML. Using this part of the XML Writer activity will require the ability to write XPath queries.

To Write All Data Item Values to XML

  1. If you have not already done so, use one of the following methods to select the XML file to update:

    • Creating a New XML File

    • Updating an Existing XML File

  2. If you have not already done so, click the Output sub-tab and determine how you want to save the output XML file:

    • Saving the Output XML to a Data Item

    • Saving the Output XML to a File

  3. Click the Data Item Mapping sub-tab.

  4. Select the Flood Data Items to XML element option.

  5. Define the XPath query that identifies which XML element should contain the Data Item XML using one of the following methods:

    • Choose Enter Query and enter the XPath query now.

    • Choose Select Data Item and click the drop-down list to select a Data Item that will contain the XPath query when the activity runs.

  6. Click OK
    The Properties window closes.


CAP - XML Activities

  1. Click the XML Activities category in the Toolbox.

  2. Double-click the activity you want to add, or drag it to the Canvas.
    The activity is added to the process.

  3. Open the Properties for the activity (double-click the activity or right-click and select Activity Properties).
    The Properties window appears.

  4. Complete the common activity properties.


About BPM Activities

BPM Suite comes with over 60 activities that are grouped into ten categories. You can also develop custom activities to fulfill a specific purpose in your business processes.

Automated Activities

Automated activities perform functions that BPM Suite is able to automate so that no User intervention is required.

  • Connection Node

  • Calendar Delay

  • Command-line

  • Delay

  • GeoCoder

  • Get File

  • Get User Profile

  • InRule

  • Logical Expression Rules

  • MSMQ Reader

  • MSMQ Writer

  • Multi-instance Sub-Process

  • Null Activity

  • Scripting

  • Set Data Items

  • Sub-Process

Active Directory Activities

Active Directory activities create, delete, retrieve, and update Users, Groups, and Objects in Windows Active Directory.

  • Create Active Directory

  • Delete Active Directory

  • Retrieve Active Directory

  • Update Active Directory

Database Activities

Database activities retrieve information from and write information to databases.

  • SQL Executor

  • SQL Query

  • Table Reader

  • Table Writer

Desktop Activities

Desktop activities communicate process information to business users through common desktop software.

  • Email

  • Excel 2007 Reader

  • Excel 2007 Writer

  • Excel Calculate

  • Excel Reader

  • Excel Writer

  • File Writer

  • InfoPath 2007 Form Reader

  • InfoPath 2007 Form Writer

  • PDF Form Reader

  • PDF Form Writer

  • Word Writer

  • Word 2007 Form Reader

  • Word 2007 Writer

Live Meeting Activities

Live Meeting activities create, delete, retrieve, and update Microsoft Live Meetings.

  • Create Live Meeting

  • Delete Live Meeting

  • Retrieve Live Meeting

  • Update Live Meeting

Manual Activities

Manual activities assign tasks to Users.

  • Dynamic Role Assignment

  • Group Assign Activity

  • Prior Manual Activity

  • Standard Manual Activity

  • Task Completion Activity

  • User Type Assignment

Microsoft CRM Activities

Microsoft CRM activities create, delete, retrieve, and update entities in Microsoft 1.2 and 3.0.

  • Create CRM 3.0 Entity

  • Delete CRM 3.0 Entity

  • Microsoft CRM 1.2

  • Retrieve CRM 3.0 Entity

  • Update CRM 3.0 Entity

Microsoft SharePoint

The Microsoft SharePoint List Items activities allow you to create SharePoint sites and create, delete, retrieve, and update SharePoint list items.

  • Create SharePoint List Items Activity

  • Create SharePoint Site

  • Delete SharePoint List Items Activity

  • Retrieve SharePoint List Items Activity

  • Update SharePoint List Items Activity

Web Activities

Web Activities transfer information over an Internet connection via FTP, HTTP/HTTPS, or a Web service.

  • FTP

  • HTTP Request

  • HTTP Post

  • Web Service

  • Web Service (v4.4)

  • Web Service Invoker Wizard

  • WebDAV Copy or Move File

  • WebDAV Delete File

  • WebDAV Get File

  • WebDAV Get File Structure

  • WebDAV Put File

XML Activities

XML Activities manage and manipulate information stored as XML.

  • Document Generator

  • Merge XML

  • Query By Example

  • XML Reader

  • XML Writer

Custom Activities

Although BPM Suite comes with a wide variety of business activities, you may find that you want a custom activity to fill a particular need. You can take two approaches to creating a custom activity:

  • Contact Bluespring Customer Service and submit a feature request

  • Develop the activity with your own in-house resources

After you develop a custom activity, you will have to register the activity with BPM Engine and BPM Designer.


Add and Configure Activities

After you define the process information (Data Items), you can start adding activities to your process. After you add an activity to a process, you need to configure the Properties for that activity.

To add activities and configure their properties

  1. Locate the activity you want to add in the Toolbox (located on the left side of the screen).

  2. Double-click the activity or drag it to the canvas to add it to the process.

  3. Open the Properties for the activity (double-click the activity, or right-click and select Activity Properties).
    The Properties window appears.

  4. Configure the common activity properties.

  5. Configure the properties tab specific to that activity.

  6. Click OK when you are done configuring the activity.

After you have added activities to your process, you are ready to link the activities together. Links define the order of the process and let you define logic that drives the direction of the process when multiple paths are available.


Configure the Common Activity Properties

Each BPM Activity includes the following tabs:

  • General

  • Error Handling

  • Related Activities

  • Display

General

Field

Description

Name

The name you enter here appears as the name of the activityin the process. It can be up to 50 characters long.

Description

The activity description you enter here appears when Users place their cursors on the activity. It can be up to 255 characters long.

Activity Status

Click the drop-down list and select a Data Item to store the status of this activity when it completes.

Note:
The Activity Status Data Item is commonly used for error checking. For example, if an activity's status is Completed But Failed, then you can configure your process to send an email to the system administrator.

To see what Activity Status types are possible, refer to the Sys_TaskStatus table in List Management.

Error Handling

If an error occurs while an Activity is running, Error Handling allows you to define how BPM Suite should handle the error. The process and task must occur before the Activity that experienced the error.

Basic error handling

You can configure the Activity to label itself as failed and either allow or disallow the process to continue in the even of an error.

Option | Description
Mark activity as failed and continue process | After an error, the activity's status will be set to "Completed But Failed" and the process will go to the next activity.
Mark activity and process as failed and continue process | After an error, the status of the activity will be set to "Completed But Failed," the process will be set to "Failed In Progress," and the process will go to the next activity.
Mark activity and process as failed and stop process | After an error, the status of the activity will be set to "Completed But Failed," the process will be set to "Failed Stopped," and the process will stop.

Advanced error handling

You can configure the Activity to roll back the process to a different process and activity. Advanced error handling is often used to notify the process owner of an issue with the process.

  1. Click the Select Rollback Process button. The Select Rollback Process window appears.

  2. Select the process to roll back to if the activity experiences an error and click OK. The name of the process appears in the Rollback process field.

  3. Click the Rollback activity drop-down list and select the activity within the Rollback process where you want to start.

  4. Click the Edit Data Item Mappings button. The Map Data Items between the Main Process and Sub Process window appears. If you need to make data items in the main process available to the rollback process, select them in the left-hand column and click the Map > button to copy them to that process if an error occurs.

Related Activities

Serves as a reference tab for viewing Activities that are linked to the selected Activity.

Field | Description
Parent Activities | This read-only field displays the activities that precede this activity, including all branching criteria.
Child Activities | This read-only field displays the activities that follow the current activity, including all branching criteria.

Display

Determines how a task appears on the canvas in BPM Designer and on the Process View tab in BPM Web.

Section | Description
Icon Properties | Click the Change Icon button to open a window that allows you to browse for a new icon for the activity. Click the Use Default Icon button to change the icon back to the standard icon.
Border Properties | Click the Border Shape drop-down list to define the shape of the border for the activity. Click the Border Style drop-down list to define style of the border line. Click the Border Color drop-down list to define the color of the border line.
Text Properties | Click the Text Alignment drop-down list to define the alignment of the title of the activity. Click the Change Text Color button to define the color of the title of the activity. Click the Edit Font drop-down list to Font, style, and size for the title of the activity.

Related Topics

Understanding BPM Activities


Copy and Paste Activities between Processes

You can copy and paste activities that you have already configured. You can paste the activities into the same process or a different process.

To copy and paste activities

  1. Select the activity or activities you want to copy.

    Tip:
    Hold the Shift key while you click activities to select more than one.

  2. Right-click the activity you want to copy and select Copy.

  3. Complete one of the following:

    If you want to paste

    Then

    The activity to the same process

    Keep the current process open and go to step 4.

    The activity to a different process

    Open a different process and go to step 4.

  4. Right-click the Canvas and select Paste.
    The copied activities appear on the Canvas.


Insert Activities on a Link

You can insert an activity in the middle of the link without having to remove or replace any links.

When inserting an activity into a link with a logical expression, the expression will apply to the link between the new activity and parent activity. The logical expression will not apply between the new activity and the next activity in the process.

Example:

If a report is approved during a manual activity, it goes one way, but if it's rejected, it goes another way. You want to insert an activity between the manual activity and the next activity on the approval site. The approval conditional link will connect the manual activity and the inserted activity; not the inserted activity and the next activity. That link will turn into a standard link.

To insert an activity on a link

  1. Click the link on which you want to insert an activity.

  2. Right-click the link on which you want to insert an activity and select Insert Task > Activity Category > Activity.
    Select the Activity Category you want, then click the Activity you want.

The activity is inserted into the middle of the link.


Remove Activities from Processes

If you have unlinked activities on the Canvas, you will not be able to save the process. You can remove these activities and then save your process.

To remove an activity from a process

  1. Click the activity you want to remove.

    Note:
    Do not click the activity icon in the Toolbox. If you do, you will add another activity to your process.

  2. Press the Delete key.
    The activity is removed from your process.


Replace Activities

You can replace one BPM Activity with another without activity breaking any links.

To replace an activity in your process

  1. Right-click the activity you want to replace and select Replace with > Activity Category > Activity.
    Select the Activity Category you want, then click the Activity you want.

The activity is replaced and your link remains in place.

Note:
You will need to complete the information about the new activity.


Defining your Company's Work Week and Hours

Defining your company's work week and hours will ensure that tasks are assigned only to Users who are available to complete them.

To define your company's work week and hours

  1. Click the Configuration Management menu and select Business Calendar.
    The Business Calendar window appears.

  2. Click the Time Periods/Workday tab.

  3. Click the check box above each day your company considers a work day.
    When you click a day of the week, you can select the work hours for that day.

  4. Select the Start Time and End Time from the lists below each work day you clicked.

  5. Click the File menu and select Save to save your work.


Scheduling Company Holidays

You can schedule company holidays to ensure that tasks are scheduled and assigned only when Users are available to complete them.

To schedule company holidays

  1. Click the Configuration Management menu and select Business Calendar.
    The Business Calendar window appears.

  2. Enter the name of the company holiday in the Description field.

  3. Select the date of the holiday on the calendar.

    Tip:
    Use the left and right arrows to move backward and forward through the months.

  4. Select the check box for the states in which your company has local branches.

  5. Click the Add/Update button.
    The company holiday is added to the list at the bottom of the Business Calendar window.

  6. Click the File menu and select Save.


Using the Business Calendar

You can set up a Business Calendar by entering information about your company's work week, hours, and holidays.

BPM Suite uses the Business Calendar when tasks are assigned. For example, if your company's work week is Monday through Friday, then no tasks will be assigned or expire on Saturday or Sunday.

Managing the Business Calendar

  • Defining Your Company's Work Week and Hours

  • Scheduling Company Holidays

Important Note

In order for a manual activity to make use of the business calendar, a User's profile must include a value for State and Zip Code. These are not required values for all User profiles, so you should use Access Management to ensure the profiles include this information.


Accessing Geography Management

You can access the Geography Management window using the Configuration Management menu.

To open the Geography Management window

  • Click the Configuration Management menu and select Manage Geography [image] .
    The Geography Management window appears.


Adding Geographies

You can create Geographies to include within Geography Sets.

To add a Geography

  1. Open the Geography Management window and select the Geography Set in the upper left pane to which you want to add a Geography.

  2. Click the Add Geography button [image].
    A new Geography appears in the Geography Set.

  3. Enter a name for the new Geography and press the Enter key on your keyboard.

  4. Click the File menu and select Save.
    The Geography Set has been updated.


Adding Geography Codes

You will add Geography Codes to a Geography to define your business locations.

To add a Geography Code

  1. Open the Geography Management window and click the Geography in the upper left pane for which you want to add a Geography Code

  2. Click the Add Geography Code button [image].
    The Add GeoCode(s) window opens.

  3. Click the + button next to the state that contains the geographic location you want to add
    The list expands to show all counties in that state.

  4. Continue to click the + button until you reach the level at which you want to assign a Geography Code.

  5. Double-click that level or press Enter.
    The Geography Code(s) appear in the right pane.

    Note:
    If you did not reach a sub-city, any levels below the level where you stopped will be marked with a wild card.

  6. Click OK.
    The Add GeoCode(s) window closes and the Geography Code you selected appears in the right pane of the tab for the Geography Set you selected originally.

  7. Click File > Save.
    The Geography Set is updated.


Adding Geography Sets

A Geography Set contains all of the Geographies that serve a common purpose. Geography Sets group several Geographies together to designate a region to which tasks can be assigned.

To add a Geography Set

  1. Open the Geography Management window and click the Add Geography Set button [image].
    A new Geography Set is added to the list.

  2. Enter a name for the new Geography Set and press Enter on your keyboard.

  3. Click the File menu and select Save.
    The list of Geography Sets has been updated.


Adding Geography Users

Assigning a User to a Geography

You can add Geography Users to Geographies.

To add a Geography User

  1. Open the Geography Management window and click the + next to the Geography Set with the Geography to which you want to add a User.
    A list of Geographies within that Geography Set appears.

  2. Select the Geography to which you want to add a Geography User.
    A list of available Users appears in the Non-Member list below the Geography Sets.

  3. Select the User you want to add to the Geography.

  4. Click the Add Geography User button [image].
    The User appears in the Member list.

  5. Click the File menu and select Save.
    The Geography has been updated.


Assigning Service Locations

Type topic text here.

To assign a service location

Related topics


Removing Geographies

You can remove unnecessary Geographies from a Geography Set.

Important:
After removing a geography, no one will be able to use it.

To remove a Geography

  1. Open the Geography Management window and click the + next to the Geography Set in the upper left pane for which you want to remove a Geography.
    A list of Geographies for that Geography Set appears.

  2. Select the Geography you want to remove.

  3. Click the Remove Geography button [image].
    A window confirms that you want to remove the selected Geography.

  4. Click Yes.
    The Geography is removed from the Geography Set.

  5. Click the File menu and select Save.
    The Geography Set has been updated.


Removing Geography Codes

You can remove unnecessary Geography Codes from a Geography Set.

Note:
After removing a Geography Code from a Geography, no one will be able to use it.

To remove a Geography Code

  1. Open the Geography Management window and click the Geography Set in the upper left pane from which you want to remove a Geography Code.

  2. Click the row with the code you want to remove.

  3. Click the Remove Geography Code button [image].
    A message box appears asking if you are sure you want to remove the Geography Code.

  4. Click Yes.
    The Geography Code is removed from the Geography you selected.

  5. From the File menu, select Save.
    The Geography Set has been updated.


Removing Geography Sets

You can remove any unnecessary Geography Sets.

Important:
After removing a Geography Set, no one will be able to use it.

To remove a Geography Set

  1. Open the Geography Management window and select the Geography Set in the upper left pane that you want to remove.

  2. Click the Remove Geography Set button [image].
    A window confirms that you want to remove the selected Geography Set.

  3. Click Yes.
    The Geography Set is removed.

  4. Click the File menu and select Save.
    The list of Geography Sets has been updated.


Removing Users from a Geography

You can remove unnecessary Geography Users from a Geography.

To remove a Geography User

  1. Open the Geography Management window and click the + next to the Geography Set with the Geography from which you want to remove a User.
    A list of Geographies within that Geography Set appears.

  2. Select the Geography from which you want to remove a User.
    A list of Users appears in the Member list below the Geography Sets.

  3. Select the User you want to remove from this Geography.

  4. Click the Remove Geography User button [image].
    The User appears in the Non-Member list.

  5. Click the File menu and select Save.
    The Geography has been updated.


Using Geography Management

You can use Geography Management to designate locations by geographic location. These locations may represent an office within your organization, a region covered by a team, or the location of one individual. BPM Suite can use these locations to determine which Users are available to complete tasks.

Geography Management terms

  • Geography
    A Geography is a collection of Geography Codes that represents a location. For example, if a sales representative covers Ohio and New York, the representative would belong to both the Ohio and New York Geography Codes.

    • Adding Geographies

    • Removing Geographies

  • Geography Code
    A Geography Code is a numerical value that represents a tax jurisdiction. You can specify country, state, county, city, and township. If you want to be less specific, you can use wild cards to include all Geography Codes within a larger area.

    • Adding Geography Codes

    • Removing Geography Codes

    • Using Wild cards

  • Geography Set
    A Geography Set is a collection of Geographies that serve a common purpose. For example, a national organization that is using Geographies to manage a sales forces will have one Geography Set that covers the entire nation. Each Geography would have one or more sales representatives assigned to it.

    • Adding Geography Sets

    • Removing Geography Sets

  • Geography User
    A Geography User is a person located within a given geography.

    • Adding Geography Users

    • Removing Geography Users

Related Topics

Accessing Geography Management


Using Wild Cards

Geography Codes allow you to enter wild cards that "include all" within a group. A wild card is denoted by a zero (0) in a Geography Code and by an asterisk (*) under a country, state, and county, city, or township columns.

Example:

A sales representative is assigned to the Geography of Ohio; therefore, the sales representative is responsible for all counties, cities, and township in the state of Ohio. Using traditional methods, you would have to enter each GeoCode for each county, city, and township individually. However, you can add a wild cards to the county, city, and township columns to indicate you want to include all available counties, cities, and townships, respectively.

To use a wild card

  1. Select the Geography for which you would like to add a Geography Code.

  2. Click the Add Geography Code button on the Geography Management toolbar.
    The Add Geography Code(s) window appears.

  3. Double-click the state, county, city, or township of your desired Wild Card.
    All columns under the selection you double-clicked are marked with an asterisk (*).

  4. Click OK.
    The Add Geography Code(s) window closes.

  5. Click the Save button on the Toolbar.


Excel Templates List

Before you can read from or write to an Excel template, you must add the template to the Sys_ExcelTemplates list.

To add a file to the Excel template directory

  1. Make sure that the Excel template is stored in the BPM Suite repository folder, which by default is located on the BPM Server in C:\Program Files\Bluespring\repository\workflow\template\

  2. Open the List Management window.

  3. Double-click the Sys_ExcelTemplates list.
    The Sys_ExcelTemplates List Management window opens.

  4. Click the Value field in the empty row at the bottom of the list.

  5. Enter the name of the file exactly as it appears in the BPM Suite repository and press the Enter key.

    Example    :
    Expense_Report_Read_Values.xls

  6. Click the Save List button.

  7. Close the list.

The new list item you just created represents the actual Excel template file in the BPM Suite repository. You can select it from various drop-down lists to indicate the corresponding Excel file.

Related Topics

Using List Management | Reading Excel Values from an Excel Document in the Template Directory | Writing Data Item Values to an Excel Document in the Template Directory | Writing to an Excel 2007 Document in the Template Directory | Reading from an Excel 2007 Document in the Template Directory


InfoPath Templates List

Before you can read from or write to an InfoPath file, you must add the template to the Sys_InfoPathTemplates list.

To add a file to the InfoPath template directory

  1. Make sure that the InfoPath file is stored in the BPM Suite repository folder, which by default is located on the BPM Server in C:\Program Files\Bluespring\repository\workflow\template\

  2. Open the List Management window.

  3. Double-click the Sys_InfoPathTemplates list.
    The Sys_InfoPathTemplates List Management window opens.

  4. Click the Value field in the empty row at the bottom of the list.

  5. Enter the name of the file exactly as it appears in the BPM Suite repository and press the Enter key.

    Example    :
    Expense_Report.xml

  6. Click the Save List button.

  7. Close the list.

The new list item you just created represents the actual InfoPath file in the BPM Suite repository. You can select it from various drop-down lists to indicate the corresponding InfoPath file.


PDF Templates List

Before you can read from or write to a PDF file, you must add the template to the Sys_PDFTemplates list.

To add a file to the PDF template directory

  1. Make sure that the InfoPath file is stored in the BPM Suite repository folder, which by default is located on the BPM Server in C:\Program Files\Bluespring\repository\workflow\template\

  2. Open the List Management window.

  3. Double-click the Sys_PDFTemplates list.
    The Sys_PDFTemplates List Management window opens.

  4. Click the Value field in the empty row at the bottom of the list.

  5. Enter the name of the file exactly as it appears in the BPM Suite repository and press the Enter key.

    Example    :
    Expense_Report.pdf

  6. Click the Save List button.

  7. Close the list.

The new list item you just created represents the actual PDF file in the BPM Suite repository. You can select it from various drop-down lists to indicate the corresponding PDF form.


Process Category List

If you want to organize your processes into categories, you first need to add the names of the categories to the Sys_WorkflowCategory list.

To add a Process Category

  1. Open the List Management window.

  2. Double-click the Sys_WorkflowCategory list.
    The Sys_WorkflowCategory List Management window appears.

  3. Click the Value field in the empty row at the bottom of the list.

  4. Enter the name of the category you want to create and press the Enter key.

  5. Click the Save List button.

  6. Close the list.

The new category you just created will now be available when you categorize your processes.


Role Type List

You can use the Access Management tool to organize Roles into categories. Categories do not affect permissions in any way; they are only used to visually divide the Roles and make them easier to manage.

By default, the only Role category is General. However, you can add items to the Sys_UserClassType list to add more categories.

To add a Role category

  1. Open the List Management window.

  2. Double-click the Sys_UserClassType list.
    The Sys_UserClassType List Management window appears.

  3. Click the Value field in the empty row at the bottom of the list.

  4. Enter the name of the category you want to create and press the Enter key.

  5. Optionally, enter a description of the Role category in the TypeDesc field and press the Enter key.

  6. Click the Save List button.

  7. Close the list.

You can now organize Roles into this category in Access Management.


States List

As you configure your process, you may discover that you need to create a drop-down list of the 51 states in the United States. Because this is a common need within processes, BPM Suite comes with a list called Sys_State that contains this information.

The list contains the two-letter abbreviation for every state. If you associate the list with a Data Item, then use that Data Item in BPM Web, the list will be displayed as a drop-down list.

To access the States list

  1. Open the List Management window.

  2. Double-click the Sys_State list.
    The Sys_State List Management window appears.


Tip of the Day List

The home page of BPM Web displays news and other information, including a "Tip of the Day". You can edit the Tip of the Day through a list in List Management.

To modify the Tip of the Day list

  1. Open the List Management window.

  2. Double-click the Sys_TipOfDay list.
    The Sys_TipOfDay List Management window appears.

  3. Click the Tip field in the empty row at the bottom of the list.

  4. Enter a "tip" you want to display on the BPM Web home page and press the Enter key.

    Note:     You can enter as many tips as you want.

  5. Make sure the CSC and CSR fields are set to -1.

  6. Click the Active field for the tip you want to enable and enter -1. The tip will now appear on the BPM Web home page.

  7. Ensure that the Active field for all other tips (tips that you do not want to enable) is set to 0 (zero).

  8. Click the Save List button.

  9. Close the list.

Note:
You can use HTML formatting in your "Tip of the Day" text.

Note:

You can automatically update the "Tip of the Day" text as part of a BPM process by using a Table Writer activity to change the Sys_TipOfDay table in the BPM database.

To change the "Tip of the Day" title

You can also change the title of the "Tip of the Day" section in BPM Web. For example, you could change the title to include a welcome message from your organization.

  1. Log into the server where you installed BPM Web.

  2. Navigate to C:\Program Files\Bluespring\bpm web\BPM

  3. Locate the file web.config and open it in Notepad.

  4. Locate the following line:
    <add key="TipOfTheDay" value="Tip of the Day" />

  5. Change the value in that line to the new title you want to use for the "Tip of the Day" section.

Related Topics

Using List Management


True/False List

As you configure your process, you may discover that you need to create a drop-down list with the options True and False. Because this is a common need within processes, BPM Suite comes with a list called Sys_TrueFalse that contains those options.

If you associate this list with a Data Item, then use that Data Item in BPM Web, the list will be displayed as a drop-down list.

To access the True/False list

  1. Open the List Management window.

  2. Double-click the Sys_TrueFalse list.
    The Sys_TrueFalse List Management window appears.


User Function Type List

By default, you can organize User Functions into two categories: General and Reporting. However, you can create additional User Function types to help you organize your User Functions.

To create a user function type

  1. Open the List Management window.

  2. Double-click the Sys_UserFunctionType list.
    The Sys_UserFunctionType List Management window appears.

  3. Click the Value field in the empty row at the bottom of the list.

  4. Enter a name for User Function type in the last row of the TypeName column.

  5. Optionally, enter a description of the new type in the TypeDesc field.

  6. Press the Enter key.

  7. Click the Save List button.

  8. Close the list.

You can now use Access Management to organize User Functions by this User Function type.


Word Templates List

Before you can read from or write to a Word template, you must add the template to the Sys_WordTemplates list.

To add a file to the Word template directory

  1. Make sure that the Word template is stored in the BPM Suite repository folder, which by default is located on the BPM Server in C:\Program Files\Bluespring\repository\workflow\template\

  2. Open the List Management window.

  3. Double-click the Sys_WordTemplates list.
    The Sys_WordTemplates List Management window opens.

  4. Click the Value field in the empty row at the bottom of the list.

  5. Enter the name of the file exactly as it appears in the BPM Suite repository and press the Enter key.

    Example    :
    Budget_Agreement_Form.doc

  6. Click the Save List button.

  7. Close the list.

The new list item you just created represents the actual Word file in the BPM Suite repository. You can select it from various drop-down lists to indicate the corresponding Word file.

Related Topics

Using List Management | Writing Values to a Word Document in the Template Directory | Reading from a Word 2007 Form in the Template Directory | Writing to a Word 2007 Form in the Template Directory


Yes/No List

As you configure your process, you may discover that you need to create a drop-down list with the options Yes and No. Because this is a common need within processes, BPM Suite comes with a list called Sys_YesNo that contains those options.

If you associate this list with a Data Item, then use that Data Item in BPM Web, the list will be displayed as a drop-down list.

To access the Yes/No list

  1. Open the List Management window.

  2. Double-click the Sys_YesNo list.
    The Sys_YesNo List Management window appears.


Accessing the List Management window

You can access the List Management window via the Configuration Management menu.

To open List Management

  • Click the Configuration Management menu and select Manage Lists.
    The List Management window appears.


Adding List Items

Adding List Values

After you create a list, you can add items to the list manually.

Note:
If you have a file with information to go in your table, you can import that data directly into your table definition.

To add a list value

  1. Open the List Management window and double-click the list to which you want to add a value.
    The List Management window for that list appears.

  2. Enter the value you want to add to the list in the last row of the Value column.

    Note:
    What you enter here will appear in the list for the User to see.

  3. Press the Enter key on your keyboard.
    <New Item>     appears in the ID column in the row in which you just entered a value.

    Note:
    If you have multiple values in this table, you can order your table definition items the way you want the User to see them.

  4. Click the Save Table button.
    A window confirms the save.

  5. Click OK.
    List Management automatically assigns the list item an ID number.

Related Topics

About List Management


Allowing Only Administrators to Edit a List

Some lists contain sensitive information. In that case, you may want to allow only Users with administrator privileges to be able to change the list.

To allow only administrators to edit a list

  • While creating a list or editing an existing list, click the System drop-down list and select True.
    The list can be edited by only users with administrator privileges.


Allowing Users to Add Information to a List

Allowing Users to Add Information to a Look-Up List

You can create a look-up list that allows Users to add values to it by making it dynamic. A dynamic list looks similar to a static look-up list; however, the field allows a user to enter information. After a user enters information into the list's field and saves the changes, the information he/she entered is added to the list.

IMPORTANT:

You cannot make a list tied to an external database table dynamic. This insures that you do not change the values in the external database table.

To allow users to add information to a look-up list

  • While creating a look-up list or editing an existing list, click the List Type drop-down list and select Dynamic.
    The list now allows Users to add information to it


Caching a List's Items on a Server

Caching a List's Values on a Server

Caching list values on a server allows large lists to load more quickly, resulting in efficient process execution.

To cache a list's items on a server

  • While creating a list or editing an existing list, click the Cached drop-down list and select True.
    The list now caches its values on the BPM server


Creating a List Using Values in a Base Content Database Table

When creating a list, you have the option of automatically populating it. If the information you want to add to a list is in a table in the base content database (i.e., the same database that BPM Suite uses), you can read information from it to create your new list.

To create a list using values in a base content database table

  1. Open the List Management window and click the Add List Definition button [image].
    The Add New List window appears.

  2. Type a name for the list in the List Name field.

    Note:
    The name of your list is also used for the Cache Filename.

    Optional: Complete the list properties to perform any of the following actions

      • Allowing Users to Add Information to a Look-Up List

      • Caching a List's Values on a Server

      • Allowing Only Administrators to Edit a List

  3. Click the List Location down arrow, and then click Custom Database Table.
    The Custom Table Options field appears.

  4. Type the name of the table in the Database Table Name box from which you want to read information.

    Note:
    The name is not case-sensitive.

  5. Type the name(s) of the column(s) in the Table Columns box that you want to populate your list.

    Note:
    If retrieving data from multiple columns, enter each column in the following format:

    column name,column name,column name,etc....(No spaces after commas)

  6. Type the name of a column in the database table in the Identity Column box that you want to use to sort your new list.

    Note:
    The name in the Identity Column field cannot also be in the Table Columns field. If you typed a column name in both fields, remove it from the Table Columns field before proceeding.

  7. Click OK.
    The Add New List window closes. Your list is created and populated with the values in the columns you chose.


Creating a List Using Values in an External Database Table

When creating a list, you have the option of automatically populating it. If the information you want to add to a list is in a table in an external database (i.e., a database other than the one BPM Suite uses), you can read information from it to create your new list.

IMPORTANT: A list created using values in an external database table cannot be dynamic, meaning once it is created Users cannot add values to it outside of List Management.

To create a list using values in an external database table

  1. Open the List Management window and click the Add List Definition button [image].
    The Add New List window appears.

  2. Type a name for the list in the List Name field.

    Note:
    The name of your list is also used for the Cache Filename.

    Optional: Complete the list properties to perform any of the following actions

    • Allowing Users to Add Information to a Look-Up List

    • Caching a List's Values on a Server

    • Allowing Only Administrators to Edit a List

  4. Click the List Location down arrow, and then click External Database Table.
    The External Table Options field appears.

  5. Click the Connection Profile down arrow, and then click the database that stores the table you want to reference.

    Note:
    If the database you want to connect to does not appear in the drop-down list, then you must add the database connection.

  6. Type the table's SQL Query into the Query SQL field.

    Example:
    The following is an example query that you can use to retrieve all of the information in a table:

    Select * From [Name of Table]

  7. Type the name(s) of the column(s) that you want to populate your list in the Table Columns box.

    Note:
    If retrieving data from multiple columns, enter them in the following format:

    column name,column name,column name,etc....(No spaces after commas)

  8. Type the name of the column in the database table that you want to use to sort your new list in the Identity Column box.

    Note:
    The name in the Identity Column box cannot also be in the Table Columns box. If you typed a column name in both boxes, remove it from the Table Columns box before proceeding.

  9. Click OK.
    The Add New List window closes. Your list is created and populated with the values in the column(s) of the external database table you queried.


Creating a Simple Look-Up List

Creating a Simple List

A simple list is a list for which you manually enter each value. Create a simple look-up list if you have a small number of known values that you want to add to a list.

To create a simple list

  1. Open the List Management window and click the Add List Definition button [image].
    The Add New List window appears.

  2. Enter a name for the list in the List Name field.

    Note:
    The name of your list is also used for the Cache Filename.

  3. Optional: Complete the list properties to perform any of the following actions

      • Allowing Users to Add Information to a Look-Up List

      • Caching a List's Values on a Server

      • Allowing Only Administrators to Edit a List

  4. Click OK.
    The list is added to the list management window.

You are now ready to add values to the list.


Creating Lists

You can use List Management to create new lists, which will appear alongside the System lists already installed (denoted by the prefix Sys_*). Lists contain information you need for your configuration.

Example:
If you have a process that allows a User to enter a maintenance request for one of your apartment complexes, you can create a table that contains the name of each of your apartment complexes. Then, when you configure a Manual Activity in your process, you can create a drop-down lists that is populated with those apartment names. Later, if you build a new apartment complex, you can add the complex to the list and the name will automatically be added to the drop-down list.

To create a List Definition

  1. Open the List Management window and click the Add List Definition button [image].
    The Add New List window appears.

  2. Enter a name for the list in the List Name field.

    Note:
    The name of your list is also used for the Cache Filename.

  3. Click the List Type drop-down list and select the type of list definition you want to create.

  4. Click the System drop-down list and select one of the following:

    • True
      Only the system and Users with administrator privileges will be able to add to the list.

    • False
      Any User can add to the list.

  5. Click the Cache drop-down and select one of the following:

    • True
      The list's items will be cached on the server, which can speed up performance.

    • False
      The database will be queried for items every time the list is used.

  6. Click the Multilingual drop-down list and select one of the following:

    • True
      The list definition will be available in multiple languages.

    • False
      The list definition will not be used in other languages.

  7. Enter, in the List Order field, the name of the column that you want to use to sort the list items.

    Note:
    If you do not know the column name, you can enter it later by editing this list definition.

  8. Depending on what you selected from the System drop-down list in step 4, complete one of the following:

If you selected

Description

True

Select the Use Default Database Table option.

False

Select the Use Custom Database Table option and enter the following information about the custom database table:

  • Enter, in the Database Table Name field, the name of the table or view within SQL that contains the data.

  • Enter, in the Table Columns field, the columns within the table or view that should be accessible to the BPM Suite application.

  • Enter, in the Identity Column field, the column within the table that contains unique values.

  4. When you are finished, click OK.
    A window confirms the list was created.

  5. Click OK.
    The list appears in the List Management window in alphabetical order.

Related Topics

About List Management


Editing List Items

Editing List Values

After you create list items, you can edit the items rather than create new ones.

To edit a list value

  1. Open the List Management window and double-click the list that contains values you want to edit.
    The List Management window for that list appears.

  2. Click the row of the value you want to edit (under the Value column).

  3. Enter the new value.

    Note:
    You can also edit the order of your table definition items.

  4. Click the Save List button.
    A window confirms the save.

  5. Click OK.
    The list of items has been updated.

Related Topics

About List Management


Editing List Properties

After you create a list, you can edit the its properties.

To edit a list's properties

  1. Open the List Management window and select the list you want to edit.

  2. Click the Edit List Definition button [image].
    The Edit List window appears.

  3. Edit the properties to achieve any of the following effects:

    Allowing Users to Add Information to a Look-Up List

    Caching a List's Values on a Server

    Sorting List Items According to a Column in a Database Table

  4. Click OK.
    The list's properties are updated on the List Management window.

Related Topics

About List Management


Exporting All Rows of Data from Lists

Exporting All Values from Lists

You can export all rows of data from a list, which you can later import into a new list. Doing so can save you time, especially if your lists contain many rows of data.

Note:
If you do not want to export all the data, you can export selected rows of data from a list.

To export all the rows of data from a list

  1. Access the List Management window and double-click the list from which you want to export data.
    That list opens.

  2. Click the Export Data From List button.
    The Export List Data window opens.

    Note:
    If you have not saved your list, you will be asked to save it before exporting the data.

  3. Click the ellipsis button to the right of the Filename field.
    The Save As window appears.

  4. Browse to the location where you want to export the *.csv file.

  5. Enter a name for the exported list in the Filename field.

  6. Click the Save button.
    The Save As window closes and the file you entered appears in the Filename field on the Export List Data window.

  7. Click the Export All Rows radio button to export the entire list of data.

  8. Click OK.
    A window confirms that the file was exported successfully.

  9. Click OK.
    The data appears as a *.csv file in the location you specified in step 4.

Related Topics

About List Management


Exporting Selected Rows of Data from Lists

Exporting Selected Values from Lists

You can export selected rows of data from a list, which will allow you to import the data into a new list. Doing so can save you time, especially if your list contains many rows of data.

Note:
If you want to export all the data, you can export all rows of data from a list.

To export selected rows of data from a list

  1. Access the List Management window and double-click the list from which you want to export data.
    That list opens.

  2. Select the rows of data you want to export by holding the CTRL key on your keyboard and clicking the left-most column of the rows you want to export.

  3. Click the Export Data From List button.
    The Export List Data window opens.

    Note:
    If you have not saved your list, you will be asked to save it before exporting the date.

  4. Click the ellipsis button to the right of the Filename field.
    The Save As window appears.

  5. Browse to the location where you want to export the *.csv file.

  6. Enter a name in the Filename field.

  7. Click the Save button.
    The Save As window closes and the file you entered appears in the Filename field on the Export List Data window.

  8. Click the Export Selected Row(s) option.

  9. Click OK.
    A window confirms that the file was exported successfully.

  10. Click OK.
    The data appears as a *.csv file in the location you specified in step 5.

Related Topics

About List Management


Importing Data into Lists

Rather than manually enter items into a list, you can import a CSV file to populate a list.

To import data into a list

  1. Access the List Management window and double-click the list to which you want to add an imported list definition.
    That list opens.

  2. Click the Import Data Into List button.
    The Import List Data window appears.

  3. Click the ellipsis button to the right of the Filename field.
    The Open window appears.

  4. Locate the *.csv file you want to import and click Open.
    The Open window closes and the file you selected appears in the Filename field on the Import Lookup Data window.

    Note:
    You can only import data in CSV formatted files.

  5. Click OK.
    A window confirms that the file has been imported successfully and that the list has been modified.

  6. Click OK.
    The imported data appears in the list.

Related Topics

About List Management


Ordering List Items

Ordering List Values

Once you have added values to a list you may want to order the list values in a certain way. The order of the list values determines how they will appear when displayed in BPM Web, but not how they appear in List Management.

Note:
You can only order a list if the List Location is a Default Database Table.

To order list values

  1. Access the List Management window and double-click the list that contains values you want to order.
    The List Management window for that list appears.

  2. Click the TableOrder field for each row of values and enter the order you want that item to appear in the list.

    Note:
    Start with the number 1. If you enter multiple Table Order values of the same number, each of those list values will be given a Table Order of zero.

  3. Click the Save List button.
    A window confirms the save.

  4. Click OK.

  5. Select the list that contains values you want to order.

  6. Click the Edit List button.
    The Edit List window appears.

  7. Enter TableOrder into the List Order field.

  8. Click OK.
    The list of values has been updated.

Related Topics

About List Management


Removing List Items

Removing List Values

If a list value will no longer be used, you can delete it.

Note:
After you delete a list item, you will not be able to recover it.

To remove a list value

  1. Access the List Management window and double-click the list from which you want to delete an value.
    The List Management window for that list appears.

  2. Click the row of information you want to delete in the thin column located left of the ID column.
    A black arrow appears in the column.

  3. Press the Delete key on your keyboard.
    The item is removed from the list.

  4. Click the Save List button.
    A window confirms the save.

  5. Click OK.
    The list of items has been updated.

Related Topics

About List Management


Removing Lists

You can delete unnecessary lists if they will no longer be used by anyone.

To remove a list definition

  1. Open the List Management window and select the list you want to remove from List Management.

  2. Click the Remove List Definition button [image].
    A window confirms that you want to remove the list.

  3. Click Yes.
    The list is removed from List Management.

Related Topics

About List Management


Using List Management

You can use List Management to manage lists of information available to Users. List Management allows you to create, edit, and remove two types of lists: Dynamic and Static. A list is like a table of data from which a User can select a value when completing a Manual Activity.

You can associate a Data Item with a list, so when the Data Item is used in a Manual Activity, the Data Item will appear as a drop-down list.

Creating Lists

  • Creating a Simple List

  • Creating a List Using Values in a Base Content Database Table

  • Creating a List Using Values in an External Database Table

  • Creating a List Using Values in a SharePoint List

Managing Lists

  • Editing Lists

  • Removing Lists

  • Allowing Users to Add Information to a List

  • Caching a List's Values on a Server

  • Allowing Only Administrators to Edit a List

Managing List Items

  • Adding List Items

  • Editing List Items

  • Removing List Items

  • Ordering List Items

  • Exporting Selected Rows of Data from Lists

  • Exporting All Rows of Data from Lists

  • Importing Data into Lists

Related Topics

Accessing the List Management window


Accessing Notification Templates

You can access the Template Editor window using the Configuration Management menu.

To open List Management

  • Click the Configuration Management menu and select Manage Notification Templates [image].
    The Template Editor window appears.


Copying Notification Templates

You can copy existing notification templates.

Tip:
If you are creating the same notification template for all three distribution methods, you can save time by creating the notification template once and then copying and updating the options twice.

Example:
Create an Email notification template. Copy the template and change its distribution method to SMS.

To copy a notification template

  1. Open the Template Editor window and click the Create Copy of Saved Template button [image].
    The Copy Template window opens with a list of available templates.

  2. Select the template you want to copy from the list of available notification templates.

  3. Enter a descriptive name for this template in the Name of the new template field.

  4. Click OK.
    The template is copied, the window closes, and the template appears in the Template Editor window.

  5. Edit the notification template as necessary.

  6. Click Save when you are finished.
    The notification template is saved.

  7. Close the Template Editor window.

Related Topics

Accessing Notification Templates


Creating Notification Templates

In addition to the default notification templates available in BPM Suite, you can create your own notification templates to use.

To create a notification template

  1. Open the Template Editor window and click the Create New Template button [image].
    The New Template window appears and asks you to name your new template.

  2. Enter a descriptive name for your new template in the Name of the template field.

  3. Click OK.
    Your template is created and saved.

  4. In the Options section, complete the following information as necessary.

    In the

    Do the following

    Template Name

    Enter the name of your template.

    Note:
    This is the same name you entered in step 2.

    Trigger Event

    Select the event on which you want this notification message to be sent.

    You have the following options:

    • Task Assigned
      Sent when a manual task is assigned.

    • Task Reassigned
      Sent when a manual task is reassigned.

    • Task Escalated
      Sent when a manual task is escalated.

    • Task Timeout
      Sent when a manual task times out.

    • Task Completed
      Sent when a manual task is completed.

    Distribution Method

    Select the distribution method you want this template to use.

    Note:
    After saving your notification template for the first time, you cannot change the distribution method, because it could affect an existing activity configuration.

    Priority

    Select the priority level for this notification.

    Note:
    The Priority option is only available when the Distribution Method is via Email.

    Message Type

    Select the type of message you want to send.

    Note:
    The Priority option is only available when the Distribution Method is via Email.

    Note:
    The HTML option allows you to change the style and format of your Email notification using a toolbar similar to Microsoft Word. Some Email clients may have difficulty interpreting HTML, in which case Plain Text is a better option. You may want to contact potential recipients to see what they recommend or prefer.

    Subject

    Enter the subject of this Email or SMS.

  5. Enter the message to be sent in the large field below the Options section.

    Note:
    To include dynamic information in your message, drag a Data Item from the list of Available Data Items to the message field. Click the Value option at the bottom of the Available Data Items field to use the Data Item's value, or click the Display Value option to use the Data Item's Display Value. The Display Value and the Value may not be the same.

    Example:
    %Manager_Approved.DisplayValue% = "Yes"
    %Manager_Approved.Value% = 1

  6. Click Save when you are finished.
    The notification template is saved and is ready to be used by a manual activity.

  7. Close the Template Editor window.

Related Topics

About Notification Templates


Editing Notification Templates

You can edit both default notification templates and notification templates created by you and other administrators.

To edit a notification template

  1. Open the Template Editor window and click the Load Template button [image].
    The Load Template window opens with a list of available templates.

  2. Select the template you want to edit from the list of available notification templates.

  3. Click OK.
    The window closes and the template appears in the Template Editor window.

  4. Under the Options section, edit the following information as necessary

    In the

    Do the following

    Template Name

    Enter the name of your template.

    Trigger Event

    The Trigger Event cannot be changed after the first save.

    Distribution Method

    The Distribution Method cannot be changed after the first save.

    Priority

    Select the priority level for this notification.

    Note:
    The Priority option is only available when the Distribution Method is via E-mail.

    Message Type

    Select the type of message you want to send.

    Note:
    The Message Type option is only available when the Distribution Method is via E-mail.

    Note:
    The HTML option allows you to change the style and format of your e-mail notification using a toolbar similar to Microsoft Word. Some e-mail clients may have difficulty interpreting HTML, in which case Plain Text is a better option. You may want to contact potential recipients to see what they recommend or prefer.

    Subject

    Enter the subject of this message.

    Note:
    You can include dynamic Data Item values in your subject line by dragging Data Items from the list of Available Data Items to the Subject field.

    Note:
    This Subject option is only available when the Distribution Method is via E-mail or SMS. With SMS, some service providers display the subject line and others hide the subject line.

  5. In the large field below the Options section, enter the message to be sent.

    Note:
    To include dynamic information in your message, click and drag a Data Item from the list of Available Data Items to the message field. Click the Value option at the bottom of the Available Data Items field to use the Data Item's value, or click the Display Value option to use the Data Item's Display Value. The Display Value and the Value may not be the same.

    Example:
    %Manager_Approved.DisplayValue% = "Yes"
    %Manager_Approved.Value% = 1

  6. Click Save when you are finished.
    The notification template is saved.

  7. Close the Template Editor window.

Related Topics

Accessing Notification Templates


Removing Notification Templates

If a notification template is no longer being used, you can remove it.

Important:
Verify that this notification template is not being used by any manual activities before deleting it. Otherwise, the users may not receive a notification when assigned a task.

To create a notification template

  1. Open the Template Editor window and click the Remove Template button [image].
    The Remove Template window opens with a list of available templates.

  2. Select the template you want to remove from the list of available notification templates.

  3. Click OK.
    The template is removed from the list and the window closes.

Related Topics

About Notification Templates


Using Notification Templates

You can create standard notification templates to use with manual activity notifications, which can include Email and SMS.

BPM Suite comes with 15 default templates, which include default task assignment, task completion, task escalation, task reassignment, and task timeout notifications. Each includes a default Email and SMS.

Managing Notification Templates

  • Creating Notification Templates

  • Copying Notification Templates

  • Editing Notification Templates

  • Removing Notification Templates

Related Topics

Accessing Notification Templates


About Time Zone Configuration

You can use Time Zone Configuration to manage time zones for your company's Geographies.

By defining time zones, BPM Suite will be able to automatically assign tasks to a person in the desired geography.

Managing Time Zone Configuration

  • Setting Time Zones for Geographies

Related Topics

Accessing the Time Zone Configuration window


Accessing the Time Zone Configuration window

Accessing Time Zone Configuration

You can access the Time Zone Configuration window via the Configuration Management menu.

To access the Time Zone Configuration window

  • Click the Configuration Management menu and select Geography/Time Zone Configuration.
    The Time Zone Configuration window appears.


Setting Time Zones for Geographies

You can define and change a Geography's Time Zone if necessary.

To set a time zone for a geography

  1. Open the Time Zone Management window.

  2. Click the Time Zone GeoSet drop-down list and select the Geography Set that contains the Geography for which you want to define a time zone.
    All of the Geographies in the Geography Set appear in the Geography column.

  3. Click in the Time Zone column for the Geography whose time zone you want to change.
    The field changes to a drop-down list.

  4. Click the drop-down list and select the appropriate time zone.

  5. Click the File menu and select Save.
    The Geography's time zone has been changed.

Related Topics

About Geography/Time Zone Configuration


Changing the Type of a Data Item

A Data Item's type defines the amount and type of information it can hold. Refer to the table below for more information on the types.

Data Type | Description
Binary | Intended to contain binary information (raw computer data in the form of ones and zeros) when the total amount of data is limited to 255 bytes.
Boolean | Intended to receive yes/no logic. Creates a checkbox when used in BPM Web. The return values are 1 if checked, 0 if unchecked. The return display values are True if checked, False if unchecked.
Byte | Intended to hold a number between 0 and 255.
Char | Intended to hold a string of text or numbers.
Comment | Intended to hold a string of text. Creates a text label when used in BPM Web. The label displays the value of the Data Item.
Currency | Intended to hold dollar amounts.
Date | Intended to hold the date in the format DD/MM/YY.
DateTime | Intended to hold the date and time in the format DD/MM/YY HH:MM:SS AM/PM.
Decimal | Intended to hold non-whole numbers.
Double | Intended to hold numbers larger than will fit in a Single Data Type.
FilePointer | Holds a Windows directory path to a file, usually located in the BPM Suite file repository. Creates an Upload/View File field in BPM Web. If you use the DocView.aspx plugin, then the actual file is displayed within a tab in the right pane of the task winow.
GUID | Intended to hold a fixed-length GUID (Globally Unique Identifier), which is a completely unique strings of letters and numbers that identifies something within BPM Suite (e.g., an Activity, a Process, etc.).
HTML | Intended to hold HTML. When "Read Only" in the common properties is not checked, text can be formatted as rich text (RTF) in Manual Task plug-ins.
Hyperlink | Intended to hold data that can act as a hyperlink (e.g., http://www.bluespringsoftware.com).
Integer | Intended to hold whole numbers between -32,768 and 32,768.
Long | Intended to hold long values, such as when a Data Item is connected to a list.
LongBinary | Intended to hold images, OLE objects, or other complex data. OLE objects are information created in a Microsoft application that can be embedded in a second application (such as an Excel spreadsheet embedded in Word).
Memo | Intended to hold text or numbers of variable length up to a very large size.
Single | Intended to hold whole numbers larger than will fit in an Integer Data Type.
Text | Intended to hold text (letters and numbers) up to 255 bytes.
Time | Intended to hold the time in the format HH:MM:SS AM/PM.
UserID | Intended to hold a User's ID number, along with other information necessary to escalate tasks.
VarBinary | Intended to contain binary information (raw computer data in the form of ones and zeros) when the total amount of data is not known.


Configuring Data Item Properties

Data Item properties describe the attributes of a Data Item. You can configure these properties in the Data Item Management window.

  1. Open a process or create a new process.

  2. Click the Data Item Management button on the Process Designer toolbar. The Data Item properties are presented on a grid.

  3. Click the field for a property to change it.

Property

Description

XML Tag

The name of the Data Item as entered when created. Cannot contain spaces or any of the following characters: \ / : * ? " - _ < > | '

Note:
Spaces, hyphens and underscores are removed when the Data Item is added to the process.

Attribute Name

The name of the Data Item as entered when created. Can contain spaces, but cannot contain the following characters: \ / : * ? " - _ < > | '

Default Value

Data Items can be given a default value which will be used when the process starts, unless the value is changed when the process runs.

Data Items do not need to be given a default value.

Note:
If you give a Data Item an expression value, like NOW(), and use it in a SQL query, the Data Item value will give you the calculated value and not be stored as NOW().

Multiple Values

True (checked) or False (unchecked) value that determines whether the Data Item can store multiple values.

Data Items can receive multiple values from activities such as Table Reader. Multiple value Data Items can then be used with a Table Writer activity or a Multi-Instance Sub-Process.

Note:

When using Microsoft InfoPath, Data Items with multiple values are grouped together in an instance based section of columns.

Example:
If you have the following Data Items in your process: Customer, Product_ID, Product_Description, and Product_Price then those Data Items will have their own column. Data Items can store multiple values. The Customer Data Item would not be included in the instance based section of columns. Also, there can only be one instanced based section on an InfoPath form.

Inherit Properties

True (checked) or False (unchecked) value that determines whether the Data Item will inherit its properties from the parent process or use its own.

  • Check the check box of the child process Data Item to inherit the default Data Item properties from the parent process Data Item.

  • Un-check the check box in order to edit the properties in Data Item Management.

LU Table

Allows you to associate a list with a single Data Item.

Note:
The Inherit Properties option must be unchecked and the Data Type should be set to Long.

Lists are defined through List Management.

Data Type

Allows you to determine what type of information and in some cases how much information can be stored in a Data Item.

Note:

If you assign a manual task to a User, make Data Items available to that User, and if the User accesses the task through BPM Web, the Data Type of those Data Items determines what type of field will appear for the user.

  • To create a Text Box, make the Data Type Text or HTML. You can set the maximum length.

  • To create a Drop-Down List, set the Data Type to Long and select the LU Table to use as the list.

  • To create a Check Box, set the Data Type to Boolean.

  • To create an Upload/View File field, set the Data Type to FilePointer.

  • To create a header/comment, set the Data Type to Comment.

  • If a field will only hold numbers, select one of the following Data Types: Binary, Decimal, Double, Integer, Long, or Single. The filed will look like a Text Box.

Use the Data Type User ID if you are going to store a User's ID.

Max Length

Determines and limits the maximum number of characters that can be stored or entered into a Data Item.

A blank field means that you can type an unlimited number of characters.

Mask

Allows you to "mask" the information stored in a Data Item. You can mask credit card numbers so they only display the last four digits. You can also mask dates, so they appear in a given format.

EIC

Allows you to use a custom DLL with a Data Item. Custom DLLs can be developed with Microsoft Visual Studio .NET.

Web EIC

Allows you to use a custom Web plugin or User Control with a Data Item. Custom Web plugins and User Controls can be developed with Microsoft Visual Studio .NET. Enter the URL of the Web plugin or User Control in the field.


Connecting Data Item to List

Connecting a Data Item to a List

You can connect any Data Item to a list by modifying the Properties of the Data Item in Data Item Management.

  1. Click the Data Item Management button on the Process Designer toolbar.

  2. Create a Data Item that you want to connect to a list, or select an existing Data Item that you want to connect to a list.

  3. Click the LU Table field for that Data Item. A drop-down list appears.

  4. Click the drop-down list and select the list that you want to connect to this Data Item.

  5. Click OK.

The Data Item is now populated with the contents of the list, and will always reflect the most current list contents. If you use this Data Item in BPM Web, the Data Item will appear as a drop-down list.


Copying Data Items from Process

Copying Data Items from Another Process

You can copy Data Items from any existing process. You can copy all Data Items, or only those that apply to the new process.

  1. Click the Data Item Management button on the Process Designer toolbar.

  2. Click the Copy Data Items button, located in the upper-left corner of the window.
    A window that displays a list of processes appears.

  3. Navigate through the hierarchy of processes to find the process whose Data Items you want to copy.

  4. Select the process and click OK.
    The Copy Data Items window appears.

  5. Copy Data Items through one of the following methods:

    • Select the Copy option for each Data Item you want to copy to the new process.

    • Select the Copy all Data Items option to copy all Data Items.

  6. Inherit Data Item properties through any one of the following methods:

    • Select the Inherit Properties option for any Data Item you are copying whose properties you want to inherit.

    • Select the Inherit Properties for all Data Items option to inherit properties for every Data Item you are copying.

    Note
    Inheriting Data Item properties means the new Data Item will have the same Data Type, default values, and other properties as the original Data Item.

  7. Click OK.


Creating a Data Item

Data Items are the basic units of information in BPM Suite. They can hold information provided by end users, display options in a list, and much more.

After you determine which Data Items your process requires, you can create Data Items with the Data Item Management tool.

To create a Data Item

  1. Open a process or create a new process.

  2. Click the Data Item Management button on the Process Designer toolbar.
    The Data Item Management window appears.

  3. Click the Create a user defined Data Item field and enter a descriptive name for the Data Item.

    Example:
    If you need to store the name of a customer, enter CustomerName or Customer_Name.

    Note:
    The name you enter here is the name other Users and Business analysts will see, so it is helpful to be descriptive.

  4. Click the Add Data Item to List button.
    The Data Item appears in the list of Previously Selected Data Items.

    Note:
    For more information on Data Items, see the Help topics available on the Define Process Information page.

  5. Click OK.
    The Data Item Management window closes.


Define Process Information

Define Process Information (Data Items)

After you create a new process and define its Properties, you should create Data Items to contain the information you will need to use in the process. You can create Data Items at any time, but Data Items are often required to configure activities, so it's a good idea to create them now.

A Data Item is a container for information. Almost all the information passed through BPM Suite comes in the form of Data Items. For example, if you create a Web form that uses fields to collect information, each field represents a Data Item. The Data Item defines how the field looks, what kind of data can be accepted, and more. If you wanted to create a Web form that collects personal information about someone, you might create the following Data Items:

  • First Name

  • Last Name

  • Phone Number

  • Email Address

  • Address Line 1

  • Address Line 2

  • City

  • State

  • Zip Code

Data Items have many uses. Read the following topics to understand how you can use them in your business processes:

  • Creating a Data Item

  • Configuring Data Item Properties

  • Changing the Type of a Data Item

  • Storing Multiple Values in a Single Data Item

  • Storing a File in a Data Item (File Pointer)

  • Storing a User ID in a Data Item

  • Connecting a Data Item to a List

  • Copying Data Items from Another Process

  • Mapping Data Item Values Between Processes

  • Defining Acceptable Input for a Data Item (Masking)

  • Understanding System Data Items

  • Understanding the Different Between Value and Display Value


Defining Data Item Mask

Defining Acceptable Input for a Data Item (Masking)

In some circumstances, you may want to limit the possible characters that a Data Item can hold. This kind of limitation is called a mask.

For example, multiple users might enter the value of an expense report very differently (e.g. $10.00, $10, 10.00, etc.). This variation can make a Data Item difficult to work with. To overcome this potential problem, you can create a mask that defines how data in a Data Item must be formatted.

A mask only affects the appearance of a Data Item, not the Data Item's contents. So if you create a mask that shows the user certain characters, those characters will not be included in the final contents of the Data Item.

To create a mask, click the Mask field of a Data Item (in Data Item management) and enter the following special characters to define the formatting of the Data Item contents.

Character | Masking Function
0 | Digit (0 to 9, entry required, plus (+) and minus (-) signs not allowed)
9 | Digit or space (entry not required, plus and minus signs not allowed)
# | Digit or space (entry not required, spaces are displayed as blanks while in Edit mode, but blanks are removed when data is saved, plus and minus signs allowed)
L | Letter (A to Z, entry required)
? | Letter (A to Z, entry optional)
A | Letter or digit (entry required)
a | Letter or digit (entry optional)
& | Any character or a space (entry required)
C | Any character or a space (entry optional)
$ . , : ; - / | Decimal placeholder and thousand, date, and time separators. (The actual character used depends on the settings in the Regional Settings section of the Windows Control Panel).
< | Causes all characters following to be converted to lowercase
> | Causes all characters following to be converted to uppercase
~ | Turns character case conversion off
* | Causes the following characters to be hidden (password characters)
! | Turns password characters off
{ | Starts list of valid characters. The valid characters list is case sensitive.
} | Ends list of valid characters
+ | Character must match a character in the most recently defined valid char list. Entry required.
= | Character must match a character in the most recently defined valid char list. Entry not required.
\ | Causes the character that follows to be displayed as the literal character (for example, \A is displayed as just A).

In the example above, you might enter this mask:

$00.00

When the user views the Data Item, he or she will see:

$__.__

Only the characters represented by underlines are editable, and only those will be stored in the Data Item.

Remember, the mask only affects the appearance of the Data Item, not the Data Item's contents. As a result, if the total value of the expense report is $10.00, the Data Item will contain "1000".


Mapping Data Item Values between Processes

When you create sub-processes, you will usually need to map Data Items between the parent process and the sub-process. "Mapping" Data Items can be thought of as the opposite of is the process of transferring the values in the Data Items of one process to the values

BPM Suite allows you to map values through the Sub-Process activity, the Multi-instance Sub-Process activity, and through User Assignment Persistence.

Click the links above to learn more about each method for mapping Data Item values.


Storing a File in a Data Item (FilePointer)

A FilePointer Data Item is a special type of Data Item (see the complete list of Data Item Types) that can contain a file located in the BPM Suite file repository. You might use a FilePointer Data Item to contain a file you retrieved from a networked computer via the Get File activity, or to identify an Excel document that the Excel Writer activity should write to.

Technically, the FilePointer Data Item does not actually "contain" a file. Files are located in the BPM Suite file repository, on the same server that hosts the BPM Database. The BPM Suite file repository is located in the following directory on the server:

C:\Bluespring\files\<database server>\<database name>\<site>\<file name>\

A FilePointer Data Item contains a link to a file, so manipulating the Data Item is exactly like manipulating the file itself. For that reason, we use the term "contain" to describe the relationship between a FilePointer Data Item and the file to which it links.

If you are creating a FilePointer Data Item that will contain a file that is already in the BPM Suite file repository, it is important to spell the name of the Data Item exactly like the name of the file in the directory. Otherwise, BPM Suite will not be able to reference the file.

If you make a FilePointer Data Item available through BPM Web, it will appear as a "File Upload" field. If the Data Item already contains a file, the user will be able to download it. If the Data Item is empty, the user will be able to locate a file on his or her local directory and upload that file to the FilePointer Data Item.

To create a FilePointer Data Item

  1. Open the Data Item Management window.

  2. Enter a name for the Data Item in the Create a User Defined Data Item field.

  3. Click the Add Data Item button.
    The Data Item is added to the Previously Selected Data Items list, located in the right pane.

  4. Click the Data Type drop-down list and select FilePointer.

  5. Click OK.
    The Data Item Management window closes.


Storing Multiple Values Data Item

Storing Multiple Values in a Single Data Item

A Data Item can store multiple values, but only under certain circumstances. Most activities in BPM Suite assume that a Data Item only holds one value at a time. However, the Multi-instance Sub-Process, Table Reader, and Table Writer activities are able to read and write multiple values from a Data Item.


Storing User ID in Data Item

Storing a UserID in a Data Item

A UserID Data Item is a special type of Data Item (see the complete list of Data Item Types) that holds a User's ID (the unique number assigned to the User), Role, and other information necessary to escalate tasks and perform other task functions.

You could use any type of Data Item (e.g. Text) to hold a User's ID number, but only the UserID Data Item holds all the information required to escalate tasks and identify a User's manager. For that reason, you should use a UserID Data Item when you want to assign a task to a User.

When you configure a manual activity, you can persist information about the User who completes the task by saving that information in a UserID Data Item. BPM Suite populates the UserID Data Item after the task is complete, so it always contains the information of the User who actually completed the task, even if the task was escalated. You can then use the UserID Data Item with a Prior Manual Activity to assign a different task to the same User.

The UserID Data Item gives you the flexibility to assign tasks to Users, even when you don't know which User will complete a given task when you configure it.

To create a User ID Data Item

  1. Open the Data Item Management window.

  2. Enter a name for the Data Item in the Create a User Defined Data Item field.

  3. Click the Add Data Item button.
    The Data Item is added to the Previously Selected Data Items list, located in the right pane.

  4. Click the Data Type drop-down list and select User ID.

  5. Click OK.
    The Data Item Management window closes.


Time To Complete Task Format

If you use a Data Item to provide the time source for a manual activity, the Data Item needs to be formatted as a comma-delimited string. Consider the following examples:

To Provide | The Data Item Should Contain
days, hours, minutes | 1, 2, 3 (where 1 is the number of days, 2 is the number of hours, and 3 is the number of minutes)
hours, minutes | 2, 3 (where 2 is the number of hours, and 3 is the number of minutes)
minutes | 3 (where 3 is the number of minutes)


Understanding System Data Items

System Data Items are present in every process. They cannot be shared between multiple processes, however, because each process puts its own values in the Data Items. Also, you cannot use these Data Items to store your own information. They are reserved for use by the process only.

However, you can use system data items in your processes. Five of them relate to the Delay activity.

Data Item | Description
GroupID | This Data Item uniquely identifies a process that has been started as it progresses through each activity.
EffectiveBillDate | This Data Item is mapped to a product's EBDIn XML tag.
PCSGeoCode | This Data Item is mapped to the BillGeoCode XML tag on the Customer Billing Information Section. This Data Item is required if you are deriving location information for a task. To derive location information from a task, click the When running or assigning this task, automatically derive location option on any task's General tab.
MainFlowID | This Data Item stores the process' ID.
MainFlowEventString | This Data Item tracks where the process is in its execution.
SubFlowID | This Data Item is automatically given a value when a parent process starts a child process.
ProductInDate | This Data Item is used with the Delay Activity. The ProductInDate is the date a consumer starts using a product or service. Example: High-speed Internet installation and activation date
ProductOutDate | This Data Item is used with the Delay Activity. The ProductOutDate is the date a consumer stops using a product or service. Example: High-speed Internet cancellation date
ReinstateDate | This Data Item is used with the Delay Activity. The ReinstateDate is the date a consumer or supplier reinstates the use of a product or service. Example: High-speed Internet turned on following after receiving user's payment
KeyValueChange | This Data Item is used with the Delay Activity. The KeyValueChange Data Item records the date a change happens. After its initial save and being attached to a product, the attribute under that section is changed, the process will be triggered (if KeyValueChange = True on that attribute).
ReportServerURL | This Data Item stores the Microsoft SQL Server Reporting Services URL where Bluespring reports can be accessed. The URL is commonly used in activities to download reports from SQL Server Reporting Services. The Value and the Display Value are the same. This Data Item's value is configured on the Options window.
WebBaseURL | This Data Item stores the URL to the Web site used for completing manual tasks and is commonly included in notification e-mail messages. The Value and the Display Value are the same. This Data Item's value is configured on the Options window.


Understanding Value and Display Value

Understanding the Difference Between Value and Display Value

As you configure your processes, you may find that you sometimes want to present one "version" of a value to the User and a different "version" of the value to the process. A good example is when you present a User with a list of options. You might want the User to see a list like this:

Select Your Interest in Our Company

  • Purchasing Software

  • Joining Your Partner Program

  • Learning More about Your Software

  • Other

However, you might want to use more concise values within the process, such as a number (e.g. 1-4).

In this example, the list you present to the User is a list of "Display Values", and the list you present to BPM Suite is a list of "Values". In essence, they represent the same option, just described differently.

Every Data Item has both a Display Value and a Value, but they are usually the same. There are only three ways to give a Data Item a different Display Value and Value.

  1. Connect the Data Item to a list.
    The Display Value is the Value you enter in a row.
    The Value is the ID of the row.

  2. Populate a Data Item from a list on a Web form.
    The Display Value is the User's selection (e.g. "Purchasing Software")
    The Value is any value you associate with one item in the list (e.g. "1")

  3. Use the Scripting activity.
    Write a script that specifically states what the Display Value and the Value of the Data Item should be.

Note: Most activities allow you to chose whether you intend to use the Display Value or the Value of a Data Item. If the Data Item has not been modified in one of the three ways described above, then it does not matter which value you choose. However, if the Display Value and Value are different, you need to be careful to choose the right value.


Categorizing a Process

A good way to keep your processes organized is to put them into categories. However, before you can put a process in a category, you must create categories by adding them to the Sys_WorkflowCategory list in List Management.

You can further organize processes within categories by creating Display Paths. A Display Path is a sub-category within a category. The steps to create or use Display Paths are also below.

To categorize a process

  1. Click the Process Properties button on the Process Designer toolbar.
    The Properties window appears. The General Information tab is in front.

  2. Click the Category drop-down list and select the category that should hold this process.

    Note:     If you don't see the Category you need, you need to create a new Category in the Sys_WorkflowCategory list.

  3. Optionally, if you want to organize the process within the Category, you can click the ellipsis button and select a Display Path within the Category.

    Note:     If you don't see the Display Path you need, you can type the name of a new Display Path in the Display Path field. This will create a new Display Path and put the process in it. To create even more levels of categories, you can use a backslash character in the Display Paths. For example, the Display Path Merchandise\Outdated will create a directory inside a directory.

You are now ready to configure another process property. If you do not need to configure another process property, you can begin defining process information.

Related Topics
Naming a Process | Managing the Process Category List | Defining Process Information


Changing the Process Owner

Every process has an Owner, and that Process Owner is the person who holds primary responsibility for a process. The main reason to assign or change the Process Owner is to make that User easily accessible in the event that a problem occurs in the process.

The User Type Assignment activity allows you to easily assign a task to the Process Owner.

To change the Process Owner

  1. Click the Process Properties button on the Process Designer toolbar.
    The Properties window appears.

  2. Click the Process Owner Information tab.

  3. Click the Process Owner drop-down list and select the User who holds primary responsibility for this process.

You are now ready to configure another process property. If you do not need to configure another process property, you can begin defining process information.

Related Topics
Assigning a Task to the Process Owner | Using Lock Administration | Defining Process Information


Define Process Properties

Every process has a set of properties that you can configure to determine how the process behaves.

You have access to the following process properties:

  • Naming a Process

  • Categorizing a Process

  • Offsetting the Start Date and Time

  • Setting the Process State

  • Enabling the Debug Log

  • Setting a Process Time Benchmark

  • Changing the Process Owner

  • Scheduling a Recurring Process

  • Setting Process Security

  • Viewing the Process Initiation URL


Enabling the Debug Log

BPM Suite has the ability to keep a log of the activities in any process for debugging purposes. The debug log can be enabled at two levels. First, it can be enabled system-wide (for every process) through the Options window. This feature is enabled by default, so every process records debugging information. However, recording that much debugging information can result in a loss of performance.

An alternative is to disable system-wide debugging and enable debugging for individual processes. This feature records the same debugging information as the system-wide debugging feature. If you enable debugging for selected processes, rather than enable it system-wide, you may experience performance improvements and save space in the BPM Suite database.

Note: You can still enable debugging for an individual process if the process state is set to Active, Disallow Modifications. Refer to the section "To save the debug status" below for more information.

To enable the debug log

  1. Click the Process Properties button on the Process Designer toolbar.
    The Properties window appears.

  2. Click the Other Information tab.

  3. Select the Enable Run-Time Debugging of this Process option.
    The next time the process runs, it will record information about the process in a log.

To save the debug status

If the process state is set to Active, Disallow Modifications, most features of the Process Properties window are disabled. However, you can still change the debugging status by using a button created for that purpose.

  1. Click the Process Properties button on the Process Designer toolbar.
    The Properties window appears.

  2. Click the Other Information tab.

  3. Select or de-select the Enable Run-Time Debugging of this Process option.

  4. Click the Save Debug Status button.
    The debugging status is saved.

You are now ready to configure another process property. If you do not need to configure another process property, you can begin defining process information.

Related Topics
Setting the Process State | Setting a Process Time Benchmark | Managing Debug Settings | Defining Process Information


Naming a Process

After you create a new process, you are ready to define the Properties of the process. The first property to define is the process name.

To name a process

  1. Click the Process Properties button on the Process Designer toolbar.
    The Properties window appears. The General Information tab is in front.

  2. Enter a meaningful name for the process in the Process Name field.

  3. Enter a description for the process in the Description field.

You are now ready to categorize the process. If you do not need to configure another process property, you can begin defining process information.

Related Topics
Categorizing a Process | Defining Process Information


Offsetting the Start Date and Time

If you want a process to start before its scheduled start date or after it receives the command to start, you can configure the process to do that automatically with a Start Offset.

To understand how Start Offset works, you need to understand what can cause a process to start. Consider three events that can start a process:

  1. You click the Start Process button in BPM Designer.

  2. An external source, such as a Web form, starts a process.

  3. You start the process using the GetStartWorkflow method in the API.

In the first two cases, the start offset can only delay the beginning of the process. Because clicking the Start Process button and submitting a form both tell the process "start right now", the start process offset cannot begin earlier in time.

However, in the third case, you can set the start date and set a start offset. In effect, you can tell the process "start on this date in the future, but also use this Start Offset." For example, if you are planning to launch a new product on a certain day, you might tell the process to start on that day, but then use a Start Offset to actually start the process day or two before the launch date.

To create a start offset

  1. Click the Process Properties button on the Process Designer toolbar.
    The Properties window appears.

  2. Click the Date Related Information tab.

  3. Click the Minus/Plus drop-down list and select either Minus or Plus.
    Minus     means the process will begin running before the selected In Date.
    Plus     means the process will begin running after the selected In Date.

  4. Click the Days field and enter the number of days by which you want to offset the start. Enter 0 if you don't want to offset by any number of days.

  5. Click the Hours drop-down list and select the number of hours by which you want to offset the start. Select 0 if you don't want to offset by any number of hours.

  6. Click the Minutes drop-down list and select the number of hours by which you want to offset the start. Select 0 if you don't want to offset by any number of minutes.

You are now ready to configure another process property. If you do not need to configure another process property, you can begin defining process information.

Related Topics
Starting Test Processes | Defining Process Information


Scheduling a Recurring Process

If you have a process that should run multiple times after it is originally started, you can schedule those recurrences in the Process Properties. For example, if you have a process that automatically copies files from a networked computer and writes them to an FTP site, you might want that process to run at the end of every day, or every week.

The Schedule Recurring Process feature gives you detailed control over how frequently and at what times the process starts.

To schedule a recurring process

  1. Click the Process Properties button on the Process Designer toolbar.
    The Properties window appears.

  2. Click the Schedule Recurring Process tab.

  3. Select Non Recurring, One Time, or Recurring.
    Non Recurring     - The process will one once and then stop. This is the default selection.
    One Time     - The process will run once, then run once again at a date and time you specify.
    Recurring     - The process will run on a regular schedule that you define after it is run once.

  4. If you selected Non Recurring you do not have to configure any other settings.
    If you selected One Time, click the On date drop-down list and select the date when the process should run again, then click the At time drop-down list and select the time when it should run on that day.
    If you selected Recurring, also select the Enable Schedule option and click the Change button. A window that allows you to set the schedule will appear.

  5. Select Daily, Weekly, or Monthly and configure the detailed options for that selection.

  6. Select the daily frequency (either once per day at a specified time or on regular intervals on that day) and configure the detailed options for that selection.

  7. Click the Start Date drop-down list and select the day when it should start recurring.

  8. If necessary, click the End Date option and select the day when it should stop recurring. By default, the No end date option is selected, and the process will continue to reoccur indefinitely.

  9. Click OK.
    The scheduling window closes.

You are now ready to configure another process property. If you do not need to configure another process property, you can begin defining process information.

Related Topics
Starting Test Processes | Defining Process Information


Setting a Process Time Benchmark

If you are gathering process metrics, you may want to keep records of how long it takes a process to complete, especially for the purpose of comparing the actual time against an expected time to complete. BPM Suite automatically keeps a record of how long every process takes to complete each time it is run, and you can enter the time you expect it should take to complete. BPM Suite displays both pieces of information next to each other to help you compare the two.

To set a process time benchmark

  1. Click the Process Properties button on the Process Designer toolbar.
    The Properties window appears.

  2. Click the Other Information tab.

  3. Click the Days field and enter the number of days that you expect the process to take to run. Enter 0 if you don't expect it to take any days.

  4. Click the Hours drop-down list and select the number of hours that you expect the process to take to run. Enter 0 if you don't expect it to take any hours.

  5. Click the Minutes drop-down list and select the number of minutes that you expect the process to take to run. Enter 0 if you don't expect it to take any minutes.

You are now ready to configure another process property. If you do not need to configure another process property, you can begin defining process information.

Related Topics
Setting the Process State | Enabling the Debug Log | Define Process Information


Setting Process Security

Permission to open and view this process and its properties, but not make any changes.

Permission to make changes to the process.

Permission to view information about this process.

Permission to start this process.

Permission to restart the process after it has been started.

Permission to update these permissions for all Users, Roles, and classifications.

Permission to map this process as a child process.

Permission to change process ownership information located on the Process Owner Information tab.

Setting Process Security

You might create a process that uses sensitive information that you do not want to be available to all Users. For example, you might create a process that maintains records of employee compensation and benefits. Because that is confidential information, you might not want every User to be able to open or edit the process.

Process Security allows you to define the privileges available to a User within a process.

To set process security

  1. Click the Process Properties button on the Process Designer toolbar.
    The Properties window appears.

  2. Click the Process Security tab.

  3. Select a User, Role, or classification in the left pane.

    Note:     The rights you give to the User classification Everyone represent the minimum possible permissions for any specific User or Role. Even if you give a particular User less privileges, that User will still have the same privileges as the classification Everyone. If you want to change the permissions for only one or two Users or Roles, you should give the lowest amount of privileges to the classification Everyone and increase the privileges for particular Users or Roles individually.

  4. Select the permissions you want to make available to that User, Role, or classification in the right column.

    You can control the following permissions:

    • Read

    • Write

    • View

    • Initiate

    • Restart

    • Manage Security

    • Map as Sub Process

    • Change Ownership

You are now ready to configure another process property. If you do not need to configure another process property, you can begin defining process information.

Related Topics
Understanding User Privileges and Roles | Define Process Information


Setting the Process State

A process has three possible states. The state defines whether the process can be started and whether it can be modified. This feature is a safeguard against two possible problems.

  1. It prevents an incomplete process from accidentally running.

  2. It prevents a running process from being modified unintentionally.

When you first create a process, its state is set to Inactive, Allow Modifications. In this state, a process cannot be run, but it can be modified.

The next state you will probably choose is Active, Testing Mode. In this state, a process can be run and it can be changed. You will probably use this process state while working out the details of a process configuration.

The third state is Active, Disallow Modifications. In this state, a process is considered "in production" and cannot be modified. If you need to make a change, you should outdate the process and create a new version.

To set the state of a process

  1. Click the Process Properties button on the Process Designer toolbar.
    The Properties window appears.

  2. Click the Other Information tab.

  3. Click the Active State drop-down list and select the state for this process. Refer to the information above for a description of each process state.
    The process state takes effect when you click OK.

You are now ready to configure another process property. If you do not need to configure another process property, you can begin defining process information.

Related Topics
Enabling the Debug Log | Setting a Process Time Benchmark | Create a New Version of a Process


Viewing the Process Initiation URL

Every process in BPM Suite has a Web Services Description Language (WSDL) file that describes the process. You can use the WSDL file to start and manipulate (to some extent) a process. The most common use for WSDL files is to start a process through some third-party interface, such as Microsoft InfoPath or a Web form.

If you click the Generate WSDL button, BPM Suite will use your default browser to open a window that displays the WSDL file.

To view the WSDL file for a process

  1. Click the Process Properties button on the Process Designer toolbar.
    The Properties window appears.

  2. Click the Process Initiation tab.

  3. Click the Generate WSDL button.
    Your default browser will open a window that displays the WSDL file for this process.

  4. Copy the address of the WSDL from the Address bar.

    Example:     http://bpmserver/Bluespring.Webservices/bpm/1001/Processes.ashx

  5. Paste this WSDL file address into a Web form or third-party application as necessary to start the process.

Please refer to the Bluespring SDK document for more ways to use the WSDL file.

You are now ready to configure another process property. If you do not need to configure another process property, you can begin defining process information.

Related Topics
Define Process Information


Create Default Links

Default links are used in combination with Logical Branching Links. They indicate the path that will be followed if no logical expressions evaluate to true.

Example
If there are on two Logical Branching Links coming off an activity and they both return false, then the process will stop. But if a Default link is added, then the path would continue down the default path even if both Logical Branching Links return false.

To create a default link

  1. Link two activities.

  2. Open the properties for the link (double-click the link or right-click and select Link Properties).
    The Properties window appears.

  3. Click the Link Type drop-down list and select Default Link.

  4. Optionally, click the Critical path? drop-down list and select one of the following options:

    • Select Yes if the process must take this link in order to complete successfully.

    • Select No if the process does not need to take this link in order to complete successfully.

  5. If this link connects to a Connection Node, then you may want to set the Wait on activity property.

  6. Optionally, click the Display label box and enter a label for this link that will appear on the Canvas.

  7. Click OK to close the Properties window.


Create Logical Branching Links

If You Did Not Use Data Items

If you did not use any Data Items in your logical expression, you can just click the Test Expression button to see the result of your logical expression.

The result of your logical expression appears in the Expression Results box.

If You Used Data Items

If you used Data Items in your logical expression, then you should complete the following steps:

  1. Locate the Data Item in the Populate Variables to Test Expression list.

  2. Click the cell next to the Data Item and enter a value that you expect the Data Item might receive when the process runs.

  3. Repeats steps 1-2 for all Data Items in your logical expression.

  4. Click Test Expression.
    The result of your logical expression appears in the     Expression Results box.

Create Logical Branch Links

Logical Branch Expression links determine the direction a process should follow based on the Data Item values passed into the process.

To create a Logical Branch Expression link

  1. Link two activities.

  2. Open the properties for the link (double-click the link or right-click and select Link Properties).
    The Properties window appears.

  3. Click the Link type drop-down list and select Logical Branch Expression.
    The Link Properties window expands.

  4. Optionally, click the Critical path? drop-down list and select one of the following options:

    • Select Yes if the process must take this link in order to complete successfully.

    • Select No if the process does not need to take this link in order to complete successfully.

  5. If this link connects to a Connection Node, then you may want to set the Wait on activity property.

  6. Optionally, click the Display label box and enter a label for this link that will appear on the Canvas.

  7. Click in the large box beneath the Available Data Items list and enter a logical expression for the link to evaluate.

  8. Optionally, you can use the mathematical and logical buttons to help you write your logical expression.

  9. Optionally, you can click the Available Data Items list and select a Data Item that you want to become part of your logical expressions.
    Click the Value button to insert the Data Item's Value or click the Display Value button to insert the Data Item's Display Value.

  10. Optionally, you can test your logical expression.

  11. Click OK to close the Properties window.


Create Standard Links

A Standard Link connects two activities and does not include a logical expression.

To create a Standard Link

  1. Link two activities.

  2. Open the properties for the link (double-click the link or right-click and select Link Properties).
    The Properties window appears.

  3. Verify that the Link Type drop-down list says Standard Link.

  4. Optionally, click the Critical path? drop-down list and select one of the following options:

    • Select Yes if the process must take this link in order to complete successfully.

    • Select No if the process does not need to take this link in order to complete successfully.

  5. If this link connects to a Connection Node, then you may want to set the Wait on activity property.

  6. Optionally, click the Display label box and enter a label for this link that will appear on the Canvas.

  7. Click OK to close the Properties window.


Link the Activities

After you add and configure activities, you can link those activities to define the order and path of the business process.

You can create three types of links:

  • Standard Links
    A basic link that defines the direction of the process.

  • Logical Branch Links
    A link that evaluates a logical expression to determine which path to follow.

  • Default Links
    A link that will be followed if no other path is followed (as a result of Logical Branch links returning false).

You can use Connection Nodes to define that behavior of the process when multiple paths join.

To link activities

  1. Identify the two activities you want to connect.

  2. Click the activity that occurs first in the process.
    Eight handles appear around the activity and one handle appears in the center.

  3. Click the center handle and drag the link to the activity that occurs next in the process.
    A blue arrow with a single handle appears, which indicates that the two tasks are linked.


Use Connection Nodes

Use Connection Nodes to link multiple parent activities to the same child task and to create branches in the process definition.

Important:

Unlike other Automated Activities, Connection Nodes have a single property: Activity Dependency. In the Activity Dependency window you can view the parent activities associated with the node and define what their completion state must be before the process can continue. To define the appropriate dependency types, click the icons in the Dependency Type column.

To use a Connection Node to link tasks

  1. Add a Connection Node to the Canvas (drag the activity to the Canvas or double-click the activity).

  2. Link one activity to the Connection Node.
    The Activity Dependency window appears. The window lists all activities connected to the node and their dependency types.

  3. Click an activity to change its dependency type.
    Each activity can have one of the following dependency types:

    • Wait on Activity - indicated by a solid arrow head. The Connection Node will wait for the previous activity to complete before starting the next activity.

    • Conditional Wait - indicated by an empty arrow head. This Connection Node will wait until a predefined condition in the previous activity is met before starting the next activity.

    • Do Not Wait on Activity - indicated by an empty circle. The Connection Node will not wait for the previous activity to complete before starting the next activity.

  4. Select the Allow this connection node to complete more than once option if you want to allow the activity after the Connection Node to start more than once.

    Note:
    This option is selected by default.

  5. Click OK to close the Activity Dependency window.


Using the "Wait on Activity" Link Property

The Wait on Activity link property only applies to a link if it connects to a Connection Node. A Connection Node is the junction of several process paths. When multiple process paths combine, you might or might not want to wait for each path to reach the Connection Node before you let the process continue. The "Wait on Activity" property lets you define how the Connection Node activity will determine when it should continue the process.

The Wait on Activity drop-down list includes the following options:

  • Yes - The Connection Node will not let the process continue until the previous activity is complete.

  • No - The Connection Node will not wait for the previous activity to complete. Instead, it will allow the process to continue as soon as all links that have Wait on Activity set to Yes are complete.

  • Conditionally - The Connection Node will examine the state of a Logical Branch link to determine if it should wait for this link to complete.

While the Yes and No settings are straightforward, the Conditional option may need more explanation.

Setting a Connection Node to Conditionally Wait on a Link

  1. Open the properties of a link that may or may not need to complete before a Connection Node can let a process continue.

  2. Click the Wait on activity drop-down list and select Conditionally.
    A new drop down list called Logical Branch To Test appears

  3. Click the Logical Branch To Test drop-down list and select a logical branch in the process.
    When the process runs, the Connection Node will see if the selected logical branch link evaluated to "True". If the logical branch link evaluated to "True" then the Connection Node will wait for this link to complete before continuing.


About Designing Processes

Most of the tools in BPM Designer are designed to make it easy for Business Analysts to design business processes. This section provides information on how to use those tools effectively.

This section of the Help is organized chronologically in the order that processes are normally created.

Steps To Design a Process

  1. Plan and Outline Your Business Process

  2. Create a New Process

  3. Define Process Properties

  4. Define Process Information (Data Items)

  5. Add and Configure Activities

  6. Link the Activities

  7. Save the Process

  8. Test the Process

Demo Movies

Flash-based movie demos of BPM Designer can be accessed along with this User Guide. If you prefer to see some of the basic functions of BPM Designer as movies, these demos will introduce you quickly. Learn more about BPM Designer Demos.

Relevant Movies:

  • Process Designer Fundamentals

  • Creating Lists, Values, and Data Items
  • Using a Standard Manual Activity


Create a New Process

After you plan and outline your business process, you are ready to create a new process in BPM Designer.

To create a new process

  1. Click the Process Management menu and click Create a New Process Definition. The Process Designer window appears, and the Start and End activities are already present.

You will use the Process Designer window to graphically model your business process.

After you create a new process, you're ready to define the Properties of the process.

Note:
You can also design your process first and then create Data Items, but defining some process information first can help you get started more easily.


Parent and Child Processes

Although simple business processes may only require you to configure a single BPM process, more complex business processes will require you to create child processes (also called sub-processes). It's a good idea to think about using a sub-processes when your parent process has more than ten activities in it. Using sub-processes will help you to keep the various parts of the business process organized and understandable.

If you identify a part of your business process that is relatively self-contained, or which you want to put into a sub-process to keep the parent process clear, you should insert a sub-process activity in the parent process and configure the sub-process.

Begin setting up the parent process

Sub-processes are started by a Sub-Process or Multi-Instance Sub-Process activity in the parent process.

The Sub-Process activity starts a single process.

The Multi-Instance Sub-Process activity starts multiple "instances" (simultaneous, but slightly different copies) of one process. For example, you might use a multi-instance sub-process if you read a column of names from a table and want to start one process for each name in the table.

  1. Open the parent process.

  2. Add the Sub-Process activity to the process at the correct location for when you want it to start.

    Note:     Do not configure the activity yet. You cannot configure the Sub-Process activity until you have created the sub-process.

Setup the sub-process

  1. Create a new process.

  2. Create the Data Items necessary for the sub-process.

    Note:     If the sub-process has many Data Items in common with the parent process, you can copy all the Data Items from the parent process.

    If you want any of the Data Items in the sub-process to receive their values from the parent process, then you should select the Inherit Properties option when you configure the Data Item properties. This will ensure that the Data Item in the sub-process is capable of holding the same values as the Data Item in the parent process.

    Make sure that you have created the Data Items you need for this process to run and the Data Items that will receive their values from the parent process.

  3. Add activities to the sub-process and configure them as necessary.

  4. Save the sub-process.

    Note:     To help keep your parent and child process organized, you can categorize your sub-process hierarchically beneath the parent process.

Finish setting up the parent process

  1. Re-open the parent process.

  2. Open the properties of the sub-process activity.

  3. Click the Subprocess tab.

  4. Click the ellipsis button and select the sub-process you just created.

  5. Click the Synchronization options drop-down list and make the sub-process synchronous with the parent process or asynchronous.

  6. Click the Edit Data Mappings button and map either individual, selected, or all Data Items between the parent process and the sub-process. When you map Data Items, that means the values in the parent process Data Items will be copied to the corresponding Data Items in the sub-process.

  7. If necessary, allow certain values in the sub-process to write their values back to the parent process. If you enable this option for a Data Item, when the sub-process ends the value of the Data Item will be copied back to the Data Item in the parent process.

    For example, if the sub-process read data from a table, and you want to make that data available to the parent process, you should enable Write Back for that Data Item mapping.


Plan and Outline Your Business Process

Because your entire business process will be modeled inside the BPM Suite, you will need to know many details about your process before you can design it accurately and effectively.

Initially, do not worry about the efficiency of your business processes. You can always update the process later.

To plan and outline your business process

  1. Identify the activities involved in your business process.

    Tip:
    Start with the big process or problem you want to solve and then break it up into smaller and smaller processes until you solve your problem. You can use the Sub-Process and Multi-instance Sub-Process activities to create a process that starts related processes.

    Try to limit each process to about ten activities.

  2. Diagram these activities on the BPM Designer canvas. Or, if you prefer, you can diagram on a piece of paper, white board, or application like Microsoft Visio.
    Note any conditions that need to be met before the process can continue. Note what each activity is supposed to do, who or what should complete it, and any information (such as a customer's account number, or an Excel file) that is needed in order to complete the activity.

  3. Identify the pieces of information needed by each step.
    Information can include small pieces of information (like a "yes" or "no" answer) or big pieces of information (like corporate reports). Information can come from, and be stored in, new and existing databases.

After you diagram your process and develop information requirements, you are ready to create a new process in BPM Designer.


Save the Process

You can save your process at any time while you are designing it or when it is finished. It's a good idea to save your process after adding and defining activities and links.

To save a process

  1. If you have not already done so, define the process properties.

  2. Click the File menu and select Save.
    The process saves.

    Note:
    If any activities in the process are not configured, you will see a warning window that lists the incomplete activities. Your process will still be saved with the incomplete activities, but it will remain in the inactive state, and you will not be able to test the process.

When you finish designing the process, you are ready to start the process.


Setting the Output File Name

Some activities require you to set an output file name when saving information to an external file. The file will be stored in the repository folder on the BPM Server.

To set the output file name

  1. Click the Set Output File Name button (may be an ellipsis button or an Edit... button).
    A window appears that allows you to set up the name of the output file.
    You can include a combination of text and Data Items in the name of the file.

  2. Enter the file name in the File name text box under the Data Item drop-down boxes.

To include Data Items in your file name

  1. From the Available Data Items list box, select a Data Item you want to insert into the file name.
    The Data Item name is highlighted.

  2. Click the Insert Display Value button or the Insert Value button.
    Depending on the button you clicked, the Data Item's Display Value or Value is inserted at the cursor's position in the File name text box.

    The Data Item appears in the large field with percent signs around it. The percent signs mean the Data Item will be replaced by the value stored by the Data Item when the file is saved.

    Example:
    %FlowName%_%WorkflowID%_%TaskName%_%TimeStamp%

  3. To insert system Data Items into the file name (like a Timestamp or the Process Name), select a system Data Item from the Available Non-Data Items list box and click the Insert button.

To preview a file name with Data Item values

  1. After creating the file name, click the Preview File Name... button.
    The Preview File Name window opens.

  2. Enter test values for the Data Items in the table.

  3. After entering test values, click the Preview File Name button.
    A sample file name appears in the File name text box with the variables you entered.

  4. When you are finished, click OK.
    The Preview File Name window closes.


Test the Process

After you finish designing the process, you are ready to test it. BPM Suite provides three normal methods for starting a process and one method for testing processes before they are in production.

For more information on testing and monitoring processes, please refer to the section about Testing and Monitoring Processes.


Viewing the To Do list

Review the To Do List

You can use the To Do List to see which activities in a process need to be complete before you can save your process in Active Mode.

To review the To Do List

  1. Open a process.

  2. Click the View To Do List button [image] on Toolbar.
    The To Do list opens below the Canvas.

    Tip:
    You can sort the To Do list by clicking the column headings.


About the Process Explorer

The Process Explorer provides a convenient way to view and manage your processes. It displays a hierarchical list of every process in the database, and allows you to open, copy, outdate, delete, and export processes, as well as create new versions of processes, edit process properties, and search for processes.

The Process Explorer window is open by default when you open BPM Designer. If you close the Process Explorer, you can open it again at any time by following one of the following steps:

  • Click the View Process Explorer button on the Process Management tab.

  • Click Process Management on the main menu, and click View Process Explorer.

  • Press CTRL+F10.


Copying a Process

You can create a copy of a process, which can be useful if you want to use an existing process as a basis to begin making another process. The process copy will have all the same Activities, Links, and Data Items as the original.

To copy a process

  1. Open the Process Explorer, if it is not already open

  2. Click the Copy Selected Process button.
    A new process appears in the Process Explorer. It is named Copy Of OriginalProcessName.

  3. Double-click the new process to open it and begin making changes.


Creating a New Version of a Process

You can create a new version of a process, which is necessary if you set a process state to Active, Disallow Modifications. Once you have designated a process with this state, BPM Designer assumes you will only replace this process with a new version, never simply delete it.

To create a new version of a process

  1. Open the Process Explorer, if it is not already open

  2. Click the Create New Version button.
    A window asks you to select the date when the new version will become active.

  3. Select the date when this new process version should become active.

    Note:
    BPM Suite will automatically set the outdate of the previous version of the process to one minute before the new version becomes active.

  4. The Process Designer window for the new version of the process will appear.

  5. Modify the process as needed.

  6. Save the process. The new process will now appear on the Process Explorer with its In Date noted in parenthesis.


Exporting a Process

You can share or archive your processes by exporting them as XML or HTML.

Exporting as XML

You can export a process as XML to share the process with someone else. The XML file contains the structure of the process and the associated Data Items. However, the XML will not contain any associated lists.

Exporting as HTML

You can export a process as HTML to keep records or to document your processes. The HTML file links to a GIF image of the processes. The HTML also contains information about each Activity, Link, and Data Item in the process.

Note:

You cannot import a process that has been exported as HTML.

To export a process definition

  1. Open the Process Explorer, if it is not already open.

  2. Select the process you want to export.

  3. Click the Export Selected Process button [image].
    The Export Process window appears.

  4. Browse to the location where you want to save your exported process.

  5. Enter a descriptive name for your process in the File name field.

    Note:
    The file may already have a descriptive name. If you have defined a name in Process Properties, that name will appear in the File name field.

  6. Click the Save as type drop-down list and select either XML files or HTML files.

  7. Click Save.
    A window confirms the export.


Importing a Process

You can use BPM Designer to import two types of business processes:

  • Processes you exported from BPM Designer as XML.

  • Process diagrams created with Microsoft Visio (.vdx).

The processes can be located on any network location accessible to BPM Designer. After you import a process, you can change it as necessary.

Note
If you save an imported process in the Designer, it will not affect the original process. The imported process has a unique Process Definition ID that gets replaced during the import process.

Note

You can select multiple processes in Import Process window and import them all at once.

To import a process definition

  1. Open the Process Explorer, if it is not already open

  2. Click the Import Process button.
    The Import Process window appears.

  3. Click the Files of type drop-down list at the bottom of the window and select either XML Files or Visio Files.

  4. Browse to the location of a process exported as XML or VDX.

    Note:
    You cannot import a process that was exported as HTML.

  5. Click Open.
    The process is imported and displayed in the Process Designer.

    Note:
    The process has not yet been saved to your database. Remember to save your work when you are finished.


Opening a Process

The Process Explorer lists every current process in your database. You can use the Process Explorer to find and open any current process.

To open a process in Process Explorer

  1. Open the Process Explorer, if it is not already open.

  2. Expand the categories in the file tree as necessary to reveal the process you want to open.

  3. Double-click the process to open it in Process Designer.


Searching for Processes

You can use the Search for Processes tool to search for specific items in a process or items about a process. If you can not view a search group, click the double arrow in the title bar of each criterion to expand that section.

To search for processes

  1. Open the Process Definition Search window.

  2. Select a check box to turn on that criterion.
    You can now enter values in that box.

    Tip:
    To refine your search, check several of the available boxes and enter the search information.

  3. In the appropriate boxes, type all or part of the name

    -or-

    click the down arrow.

    If you type in the box, you can use wild cards to broaden your search.
    If you click the down arrow, a selection window appears where you can choose one or many of the listed items.

    The following table lists all criteria and what action you can take to narrow your search.

    Criteria

    Action

    Process name

    Type the process name

    Process description

    Type the process description

    Category/path

    Click the ellipsis button and select the paths

    Effective date after

    Click the down arrow and select a date

    Process state

    Click the down arrow and click one of the three states

    Process owner

    Click the ellipsis button and select the process owners

    Activity name

    Type the activity name

    Activity description

    Type the activity description

    Activity type

    Click the ellipsis button and select the Web services that execute specified actions

    Display name

    Click the ellipsis button and select the Data Item values

    XML Tag

    Click the ellipsis button and select the Data Item values

    Role assignee

    Click the ellipsis button and select the roles

    User assignee

    Click the ellipsis button and select the users

Note:
To clear the search criteria fields and begin a new search, click Clear Criteria.
To clear all results from a search, click Clear Results.

  4. Click Search.
    All processes associated with your checked search criteria appear in the right pane.

  5. In the right pane, double-click the process you want to view.
    The process opens in a new window.

    Note:
    Your specified search criteria is automatically saved in a file located at C:\Documents and Settings\Application Data. When the search screen is reopened, the saved criteria will appear.

Related Topics

Using the Process Designer | About Searching for Processes | Using Wild Cards


About Macro View

You can use Macro View to graphically arrange processes and their sub-processes. As a project manager, you can use Macro View to display all the relevant processes, including parent and child processes, multi-instance processes, and processes with incomplete items in their To Do lists.

Managing processes using Macro View

  • Process Relationships

  • Adding Processes to Macro View

  • Auto-arrange child processes

  • Nudge and align processes

  • Save views of the process

  • Opening processes from within Macro View

  • Print macro views of processes


Add Processes to Macro View

You can use Macro View to graphically display and manage your processes. Macro View allows you to quickly display parent and child processes, multi-instance processes, and processes with incomplete items in their To Do lists.

  • Displaying processes in Macro View

  • Understanding Macro View notation

Displaying processes Macro View

  1. Click the Process Management menu and select Process Macro View.
    The Processes Macro View window appears.

  2. Set the Effective Date to limit the number of processes available.

    • To view all active processes, leave today's date in the Effective Date drop-down list.

    • To view all processes that were active at a specific date, select or enter that date in the Effective Date drop-down list.

  3. Click the Load button.
    The processes in effect at the time you specified appear in the left pane.

  4. Select the type of processes you want to display.

    • Check the Processes box to display all processes.

    • Check the Nested box to display all nested processes.

    • Check the Stand Alone box to display all stand-alone processes.

The processes appear in the right pane.

Understanding Macro View notation

Use the table below to help you understand the Macro View notation.

Symbol | Meaning
Gray process | This process is enabled.
Bold outline around the process | This process has incomplete items in its ToDo list.
Bold arrow and (n) | The subprocess can be called n-number of times.
Blue asterisk and bold outline | This process is incomplete because it contains incomplete ToDo items.
Bold arrow and (#) | This subprocess is called a specific number of times.

Related Topics

About Macro View


Auto-Arranging Processes

Auto-Arranging Child Processes

You can auto-arrange child processes to make their connections easier to view.

To auto-arrange processes in Macro View

  1. Add processes to the view.

  2. Click a process that is the parent of another process.
    The process box turns from white to gray and eight handles appear around the process.

  3. Right-click the process and select Auto Arrange Child Processes.
    The child process(es) appear(s) directly under the parent process.

    Note:
    If this process has no child processes, no processes will appear under it.


Nudging and Aligning Processes

You can nudge and align processes in Macro View to make their relationship easier to see.

Tip:

To see the alignment more clearly, click the grid button on the Macro View toolbar.

To nudge a process

  • Use any one of the nudge buttons below to nudge a process up, down, left, or right.

  • To nudge multiple processes, hold the Shift key down and click the processes you want to nudge, then click a nudge button to nudge the processes.

The Nudge buttons

To align a process

  • Use any one of the align buttons below to align processes to the left, right, top, or bottom.

  • To align multiple processes, hold the Shift key down and click the processes you want to align, then click an align button to align the processes.

The Align buttons


Opening Processes from within Macro View

You can open a process from within Macro View.

To open a process from within Macro View

  1. Click a process in the right pane.

  2. Right-click the process and select View Process.
    The Process Designer window appears.


Printing Process Views

Printing Macro Views

You can use Macro View to print macro views of your processes.

To print a process view from Macro View

  1. Add the processes you want to print.

  2. Click the Print button on the Process Viewer toolbar.
    The Print Setup window appears.

  3. Select your print options from the Print Setup window.

  4. Click OK.
    The process prints.

Related Topics

About Macro View


Process Relationships

You can define parent and child relationships between processes in BPM Suite.

Parent and child process relationships

A parent process is a process from which other processes originate. A parent process can have one or many child processes. A child process is dependent on its parent processes and can be either a Sub Process or a Multi-Instance Process.


Saving Process Views

Saving Macro Views

You can use Macro View to save a macro view of the processes for future reference.

To save a view of the processes

  1. Click the Save View button on the Process Viewer toolbar.
    The Save View As window appears.

  2. Enter a name for the view in the View Name field.

  3. Optional: Click Share this view with other users to share the view.

  4. Click OK to close the Save View As window.


About Searching for Processes

You can use the Process Definition Search window to search for processes using 13 search criteria that are categorized into 4 groups. The search options allow you to narrow your query to very specific values in an existing process. To open the Process Definition Search window, do one of the following:

  • Click Process Management on the main menu, and click Search for Processes.

  • Click Search for Processes [image] on the Process Management tab.

  • Click [image] on the Process Explorer toolbar.

You can search for processes according to the information in Process Properties, the specific Activity used, the Data Items values, or the user who is tasked. To broaden your search, you can use a wild card--a character used as a substitute for any class of characters. This search expansion greatly increases the flexibility and efficiency of searches. However, you may get more results than expected with this method.

Note:

User permissions will determine the displayed results. Your specified search criteria is automatically saved in a file located at C:\Documents and Settings\Application Data. When the search screen is reopened, the previous criteria will automatically appear.

Related Auxiliary Topics


Searching for Processes

You can use the Search for Processes tool to search for specific items in a process or items about a process. If you can not view a search group, click the double arrow in the title bar of each criterion to expand that section.

To search for processes

  1. Open the Process Definition Search window.

  2. Select a check box to turn on that criterion.
    You can now enter values in that box.

    Tip:
    To refine your search, check several of the available boxes and enter the search information.

  3. The following table lists all criteria and what action you can take to narrow your search.

    If you type in the box, you can use wild cards to broaden your search.
    If you click the down arrow or ellipsis button, a selection window appears where you can choose one or many of the listed items.

Criteria | Action
Process name | Type the process name
Process description | Type the process description
Category/path | Click the ellipsis button and select the paths
Effective date | Click the down arrow and select a date. After selecting a date, click the time to specify your search
Process state | Click the down arrow and click one of the three states
Process owner | Click the ellipsis button and select the process owners
Activity name | Type the activity name
Activity description | Type the activity description
Activity type | Click the ellipsis button and select the Web services that execute specified actions
Display name | Click the ellipsis button and select the Data Item values
XML Tag | Click the ellipsis button and select the Data Item values
Role assignee | Click the ellipsis button and select the roles
User assignee | Click the ellipsis button and select the users

Note:
To clear the search criteria fields and begin a new search, click Clear Criteria.
To clear all results from a search, click Clear Results.

  4. Click Search.
    All processes associated with your checked search criteria appear in the right pane.

  5. In the right pane, double-click the process you want to view.
    The process opens in a new window.

    Note:
    Your specified search criteria is automatically saved. When the search screen is reopened, the saved criteria will appear.

Related Topics

About Searching for Processes | Using Wild Cards


Using Wild Cards

You can use wildcards to search for text. For example, you can use the asterisk (*) wildcard to search for a string of characters (for example, "d*d" finds "dad" and "deterred").

To Search Using a Wild card

  1. In the search criteria fields, type the process or activity value.

  2. Enter an asterisk before, within, and, or after the process or activity value.

  3. Click the Search button.

  4. If you entered an asterisk before the process or activity, a list of all processes or activities that end with the name you entered is displayed.

  5. If you entered an asterisk after the process or activity, a list of all processes or activities that begin with the name you entered is displayed.

  6. If you entered an asterisk before and after the process or activity, a list of all processes or activities that contain the name you entered is displayed.

  4. In the right pane, double-click the process you want to view.
    The process opens in a new window.

Related Topics

About Searching for Processes


About Finding and Viewing Processes

BPM Designer provides a set of tools to help you find and view your processes.

Process Management Tools

  • Process Explorer
    This window is open by default when you open BPM Designer. It displays a hierarchical list of every process in the database and provides the ability to open, copy, edit, export, and delete processes.

  • Process Macro View
    This tool allows you to map the relationships between processes that share a parent/child relationship.

  • Searching for Processes
    BPM Suite provides the ability to search for a process, using 13 search criteria.

  • Unlocking Locked Processes
    This tool allows you to override a User who has a process open and to unlock a process that remains locked after a user exits BPM Designer.

Demo Movies

Flash-based movie demos of BPM Designer can be accessed along with this User Guide. If you prefer to see some of the basic functions of BPM Designer as movies, these demos will introduce you quickly. Learn more about BPM Designer Demos.

Relevant Movies:

  • Initiating and Managing a Process


Unlocking Locked Processes

If you give a User permission to use Lock Administration, that User can unlock or reassign locked processes.

When a User opens a process, that process becomes locked. Other Users that open the same process will only get a read-only version, which prevents two Users from inadvertently overwriting each other's changes.

When the locked version of the process is closed, the lock is removed. If a process remains locked after the User closes the process, you can use the Lock Administration tool to manually unlock the process.

To unlock a process

  1. Click the Tools menu and select Lock Administration.
    The Lock Administration window appears.

  2. Click the Processes tab.
    All locked processes appear under the Process Definition ID column.

  3. Select the process you want to unlock.

    Note:
    Any changes made to the locked process will be lost once it is unlocked.

  4. Click the Unlock button.
    The icon for the selected process changes, which indicates that the process is unlocked.

Related Topics

About Finding and Viewing Processes


Accessing BPM Designer

You can access BPM Designer from the shortcut on your desktop or the Start menu.

To access BPM Designer from the desktop

  • Double-click the Bluespring Process Designer icon on your desktop.
    The BPM Designer login window appears.

    Note:
    You will have to configure your login settings if this is the first time you have opened the Designer since you installed it.

To access BPM Designer from the Start menu

  • Click Start > All Programs > Bluespring and select Process Designer.
    The BPM Designer login window appears.

    Note:
    You will have to configure your login settings if this is the first time you have opened the Designer since you installed it.


Configuring Login Settings

You will need to configure the login settings to point to the servers running BPM Suite.

To configure BPM Designer login settings

  1. Click Settings on the BPM Designer login window.
    The Configuration window appears.

  2. Enter or edit the following information:

From the | Enter or click
Auth Server field | The address or name of the server that hosts the BPM Engine (i.e. the PCS Security database). Example: 123.45.67.8 or SERVERNAME
Database Server field | The address or name of the server that hosts your database. Often, this is the same as the Auth Server. Example: 123.45.67.8 or SERVERNAME
Site field | The Site you are using with BPM Suite. The Site name was defined when BPM Suite was installed on the server.
Database list | The database you are using with BPM Suite.

  3. Click OK when you have finished configuring the settings.
    The Configuration window closes, and you return to the BPM Designer login window.

Related topics

Logging in to BPM Designer


Logging in to BPM Designer

You must log in to BPM Designer in order to design and manage your processes.

Note:
Your system administrator will give you your Site Key, User Name, and default Password. If you have questions about this information, please contact your system administrator.

To log in to BPM Designer

  1. Enter your site key in the Site Key field on the BPM Designer login window.

  2. Enter your user name in the User Name field.

  3. Enter your password in the Password field.

  4. Click OK.
    The Select Role for this session window appears.

  5. Select your role from the list of roles.

  6. Click OK.
    The BPM Designer window appears. You are now logged in to BPM Designer.

Related topics

Configuring login settings


Navigating the BPM Designer Toolbars

Before you get started, you may find it helpful to review the BPM Designer. This will help you understand how the Designer works and where you can find information.

BPM Designer has two toolbars:

  • Process Management
    Contains tools to design and manage business processes and activities.

  • Configuration Management
    Contains tools to manage Users, business locations, and other sources of information.

Process Management toolbar buttons

  • Save

  • Create a New Process Definition

  • View Process Explorer

  • Search for Processes

  • View/Manage Processes and Process Groups

  • View/Manage Your Process Task List

  • Edit Process Scripts

  • Edit Business Calendar

  • Edit Logical Expressions

  • Process Macro View

Configuration Management toolbar buttons

  • Save

  • Manage Geographies

  • Manage Time Zones

  • Manage Database Connections

  • Manage Lists

  • Manage Notification Templates

  • Manage Users and Roles

Related topics

Getting Started with BPM Suite and BPM Designer


Aligning tasks

Aligning Activities in the Process Designer

You can align tasks and links so they look professional. A professional-looking process can be easily understood by the people who use your process.

To align tasks

  • Align icons by holding the Shift key down while you click the icons you want to align, and then clicking an Align button to align the selected icons.

    The Align buttons.


Customizing the Process Designer Toolbox

You can customize the Process Designer toolbox by adding new categories for both activities and templates and moving current activities or templates into those new categories.

To add a new category in the toolbox

  1. Right-click the dark gray area of the toolbox.
    A drop-down list appears.

  2. Select New Category.
    The Create a New Category window opens.

  3. In the New Category field, enter the name of the category you want to add.

  4. Click OK.
    The new category you created appears in the toolbox.

To move activities or templates to a new category

  1. Click the category from which you want to move an activity.
    The category opens and all activities associated with it appear.

  2. Click the activity and drag it over the name of the new category.

    Note:
    You cannot move the Connection Node out of the Standard Activities category. The Connection Node acts similar to the Start and End nodes in the manner.

  3. Click the category into which you moved the task.
    The category opens and the activity you moved into it appears.


Nudging tasks

Nudging Activities in the Process Designer

You can nudge activities up and down or left and right on the Process Designer. Each time you nudge an activity or link, it moves one pixel in the direction you selected.

To nudge an activity

  • After selecting an activity that's been added to the Process Designer, use the Nudge buttons on the Process Designer toolbar to move the activity.

    The Nudge buttons.


Understanding process definitions

Understanding Business Processes

The processes you create in BPM Designer should directly reflect the processes that drive your business. You can use BPM Suite to automate and manage those business processes by doing the following:

  1. Identify the products and services you provide to your customers

  2. Organize the resources required to deliver those products and services

  3. Execute the tasks required to deliver your products and services

How processes work

Processes in BPM Suite are a series of predefined activities that executes your business processes and helps you to increase productivity. Processes usually begin by assigning resources and end by delivering information. The Process Designer graphically represents the activities in your processes and allows you to manipulate those activities based on your business needs.

BPM Designer provides integrated functionality and control, allowing you to do the following:

  • Assign tasks to particular users or groups of users

  • Escalate tasks (automatically and manually) to supervisors

  • Plot task progress visually to help you better manage the processes

What processes can do for your business

You can create processes and business rules in BPM Suite that accomplish the following:

  • Monitor and manage the effectiveness of both processes and personnel

  • Optimize the resources used to execute your business processes

  • Ensure service delivery to your customers


Using the Process Designer

You can use the Process Designer to create and manage business processes. The Process Designer has three main components: the Toolbar, the Activities Toolbox, and the Canvas.

The Canvas is your "work area." Here you can design your processes using the BPM Activities, which are located in the Activities Toolbox. The Toolbar contains the buttons you need to open the Properties for a process, activity, or link, and to work with a process.

The Toolbar and Activities Toolbox are essential to designing logical, easy-to-use processes.

Additionally, you can start a process from within the Process Designer. This allows you to quickly test and debug process configurations without having to use a third-party application or interface.

  • Using the Activities Toolbox

  • Using the Toolbar

  • Exporting Process Definitions

  • Importing Process Definitions

  • Starting Test Processes


Using the Process Designer toolbar

You can use the Process Designer toolbar to create logical, easily understood processes. Other users will understand your process better if it is easier to understand and follow.

To create logical, easy-to-read processes

  • Align Activities

  • Nudge Activities

  • View Tasks on a Grid

  • Zoom In or Out of a Process


Using the Process Designer Toolbox

The Process Designer contains customizable activities and any templates you create. You must configure (assign properties) and link all tasks to ensure your process runs.

You can also create a customized category tab in the toolbox to store your frequently used tasks.

  • Read more about BPM Activities


Using the Snap-To-Grid Feature

The Snap to Grid features allows you to quickly align activities to the Grid. When activities are aligned, your process design can be easier to understand and follow. You can leave the Grid turned on or off to use the Snap to Grid feature.

To use the Snap to Grid feature

  • While viewing the Process Designer, click the Snap to Grid button [image] on the Process Designer toolbar.
    Now your activities will snap to a hidden grid.

    Note:
    You can show the grid by clicking the Grid button [image] on the Process Designer toolbar. The Grid button does not have to be turned on to use the Snap to Grid feature.


Viewing Activities on a Grid

You can turn on an underlying grid that you can use to align your activities.

To view tasks on a grid

  • On the Process Designer toolbar, click the Grid button [image].

    Note:
    Click the Snap to Grid button [image] to automatically align your tasks with the Grid.


Zooming in and out of a process

You can use the zoom feature to view more or less information on the Process Designer canvas. By zooming out, you can see the whole process when it extends beyond your normal viewing area.

Tip:

Zoom out to avoid scrolling up and down or right and left.

To zoom in and out of the process

  • From the Zoom list in the Process Designer toolbar, select a percentage or enter a larger or smaller percentage to zoom in or out.

    The Zoom drop-down list.


About Process Templates

Templates are useful when you want to reuse a previous process, either as a whole or only in part. Reusing processes saves you time and gives other users a familiar method to use when they see your process.

When you save your process, it will be saved to the BPM Suite server. By saving the template to this central location, all users have access to the templates you create, and you have access to templates other people create.

Managing process templates

  • Create a new process template

  • Use a process template

  • Edit an existing process template

  • Delete a process template


Creating a new process template

Creating templates

After creating a process that will be used often, you can create a template of that process. The template stores the process's information, so you do not have to reenter details about it.

Note:
You can create a template out of a single process task or a combination of tasks, including an entire process.

To create a template

  1. After creating your process, click the tasks and links you want to include in your template.

    To select multiple tasks and links
    Hold the Control (CTRL) key on your keyboard and use your mouse to click the tasks and links you want to include. If you do not click the links connecting the tasks you want to include, they will not be included in your template.

  2. After selecting the tasks and links you want to include in your template, right-click one of the tasks or links.
    A menu appears.

  3. From the menu, select Make Template.
    The Item Properties window appears.

  4. In the Item Name field, type the name of your template.

    Note:
    When naming your template, be as descriptive as possible, so you and others know what the template can be used for.

  5. In the Item Category field, type Templates.

  6. In the Item Description field, type any notes or information about the template you think will be useful later.

  7. Click OK.
    The Select an Icon window appears.

  8. Click No to use the default icon.
    The Default icon will be used message box appears.

    Note:
    If you have an icon you would like to use, click Yes and browse to the icon file you want to use. After selecting the icon file, click OK.

  9. On the message box, click OK.


Deleting a process template

Deleting templates

If you are not going to use a template in the future, you can delete it from your list of templates.

Note:
Do not delete a template if you can use parts of the template. Instead, edit the existing template.

To delete a template

  1. From the Process Designer window, click the Template category in the Process Designer toolbox.
    All templates created by you and other users appear under the Template category.

  2. Right-click the template you want to delete.
    A menu appears.

  3. From the menu, select Delete Template.
    A message box appears asking you if you want to delete the template.

  4. On the message box, click Yes.
    The template is removed from the Template category.


Editing an existing process template

Editing templates

After creating a process template, you can edit the template's information.

Important:
When you edit and save a template, you will actually create a new template. Give the new template a unique name, so you and others know the revised template is different than the old template. If you do not need the old template, you can delete that template.

To edit a template

  1. From the Process Designer window, click the Template category in the Process Designer toolbox.
    All templates created by you and other users appear under the Template category.

  2. Click the template you want to edit.
    The template appears on your Process Designer canvas.

  3. Edit any of the following information in the table about your template:

    For the

    Do the following

    Process properties

    Right-click any task or link to view. From the menu that appears, select Process Properties.

    From the Process Properties window, you can edit information on following tabs:

    • General Information

    • Date Related Information

    • Other Information

    • Ownership/Debug

    Task properties

    Double-click the task you want to edit. From the menu that appears, select Task Properties.

    From the Task Properties window, you can edit information on the following general tabs:

    • General

    • Rollback Information

    • Display

    • Related Tasks

    Each task has its own unique tabs, which you can also edit.

    Link properties

    Double-click the link you want to edit. From the menu that appears, select Link Properties.

    From the Link Properties window, you can edit information on the following tabs:

    • Link Type

    • Critical Path

    • Wait On Task

    Template design

    Rearrange elements in the order you want them to appear by dragging and dropping them or by using the nudge and align buttons in the Process Toolbar.

  4. When you finish editing information about the template, select the tasks and links you want to include in your new template.

    To select multiple tasks and links
    Hold the Control (CTRL) key on your keyboard and use your mouse to click the tasks and links you want to include. If you do not click the links between tasks, they will not be included.

  5. Right-click one of the tasks or links you selected.
    A menu appears.

  6. From the menu, select Make Template.
    The Item Properties window appears.

  7. Complete the Item Properties information, and then click OK.
    The Select an Icon window appears.

  8. Click No to use the default icon.
    The Default icon will be used message box appears.

    Note:
    If you have an icon you would like to use, click Yes and browse to the icon you want to use. After selecting the icon you want to use, click OK.

  9. On the message box, click OK.


Using a process template

Depending on the template, you can use it to create an entire process or you can integrate it with a new process. The following describes how to insert a process into a template. After inserting the template, you can add and link other tasks to the template.

Note:
The changes you make to the tasks and links in a template will not be saved back to the template. If you make changes you would like to use in the future, you should create a new template.

To use a process template

  1. From the Process Designer window, click the Template category in the Process Designer toolbox.
    All templates created by you and other users appear under the Template category.

  2. Click the template you want to insert into your process.
    The template appears on your Process Designer canvas.

    Note:
    Now you can make changes to the template's tasks and links, link it to other tasks, or use it as it is now.


About Filtering the Active Process List

In the Process Management window, the list of active processes can get very long. Instead of looking through the entire list, BPM Suite provides tools that help you limit the results by various criteria.

Filters can narrow the scope of the view down to just the items that need to be seen or worked with at the moment. Filters do not remove data from the project, merely from the current view of active processes.

For many users, the items available to view have already been narrowed by the projects they are allowed to view from a permissions standpoint. While this narrowing of the view is not technically a filter, it is a good example of the narrowed view a filter provides.

There are two sets of filters for values: public filters and private filters. Public filters can be used and edited by anyone while private filters can only be used and edited by users who created the filter. In order to create a public filter, you must have the manage Process Filter User function.

You can determine how the filter behaves and then apply and edit filters to suit your own search needs.

  • Applying Filters

  • Creating Filters

  • Editing and Deleting Filters

  • Resetting Active Process View and Filter Settings

  • Scrolling through Process Records

  • Viewing Active Processes by Process or Process Group

Note:
Because filters are saved in a database, you can access filters from a different computer if you specify the appropriate database when you sign in to Designer.

Related Topics

Accessing the Process Management Window


Applying Filters

You can use the Select Filter down arrow to view all available filters, which appear in alphabetical order.

To apply a filter

  1. Open the Process Management window.

  2. Create a filter.

  3. Click the Select Filter down arrow.
    A list of available filters appears.

  4. Click the desired filter from the list.
    All processes that fit the conditions appear in the left pane.

    Note:
    The number of items in the folder appear in parentheses behind the folder name.


Creating Filters

You can create filters through the Filter Wizard. In this wizard, you will set the filter value to either public filters or private filters. Public filters can be used and edited by anyone while private filters can only be used and edited by users who created the filter.

To create a filter

  1. Open the Process Management window.

  2. Click the Manage Filters button in the toolbar.
    The Manage Filters window appears.

  3. Click Add.
    The View/Manage Process and Process Group Filter Wizard begins.

  4. Type the name of the new filter in the Filter name box.

    Note:
    To help identify the features of a filter, you can give a brief description in the Description field.

  5. Under Filter visibility, click the down arrow and then click Private filter

    -or-

    click Public filter.

    If you click Private filter, only you can use the created filter.
    If you click Public filter, all users can use and edit the created filter. The public filter option is only available for users in roles that have the Manage Process Filters User Function.

  6. Click Next.
    A window appears that allows you to indicate the desired criteria and edit the conditions of your search filter.

  7. In the top pane, select the conditions that you want the filter to meet.
    The selected condition appears in the lower pane.

    Tip:
    Clear a check box in the top pane to remove the related criterion from the bottom pane.

  8. In the bottom pane, click an underlined value to edit the filter condition.
    Each criterion displays a unique window that allows you to specify conditions.

  9. Click Finish.
    The Filter Wizard closes. The person who created the filter and the filter itself is saved to a database.


Editing and Deleting Filters

In addition to creating new filters, you can edit and delete existing filters if you have the security rights to manage these folders. If you do not have access to manage certain filters, you will only be able to apply the filter to the data. If a public filter is edited or deleted, the change will affect all users with access to that filter.

To edit a filter

  1. Open the Process Management window.

  2. Create a filter.

  3. Click the Mange Filters button in the toolbar.
    The Manage Filters window appears.

  4. Double-click the filter name

    -or-

    click the filter, and then click Edit.
    A window appears that allows you to change the conditions of your search filter.

  5. In the top pane, select a check box to add the related criteria in the lower pane.
    The bottom pane contains all conditions to be evaluated when applying the filter.

    Note:
    Clearing a check box removes the related criterion from the bottom pane.

  6. In the bottom pane, click an underlined value to change the filter condition.
    Each criterion displays a unique window that allows you to specify conditions.

    Note:
    Click Cancel to exit this screen without saving changes.

  7. Click OK.
    The window closes and your edits are saved to the database.

To delete a filter

  1. Open the Process Management window.

  2. Create a filter.

  3. Click the Mange Filters button in the toolbar.
    The Manage Filters window appears.

  4. Click the filter you wish to delete.
    The filter will become highlighted.

  5. Click Delete.
    A confirmation message appears, allowing you to cancel if you have selected by mistake.

  6. Click OK.
    The chosen filter is deleted from the BPM Suite database.


Resetting Active Process View and Filter Settings

Resetting Active Process View Settings

After you configure a view setting, you can use the Process Management window to return to the default view.

To reset view settings

  1. Open the Process Management window.

  2. Click the Reset Settings button.
    Zoom     and Iteration reset to the default view.

Note:
The Reset Settings button will not reset filters and filter settings.


Scrolling through Process Records

If the number of active processes in the left pane extends beyond normal view, you can scroll through the records in batches of 200.

To scroll through process records

  1. Open the Process Management window.

  2. Click the up arrow or down arrow in the Process Management toolbar to move forward or backward through your process records.


Viewing Active Processes by Process or Process Group

You can use the Process Management window to view your active processes by Process or Process Group. If you view your active processes by Process Group, you will be able to see processes grouped with any sub-processes they initiated. However, if you do not use sub-processes, you may want to view your active processes by Process.

To view active processes by Process Group

  1. Open the Process Management window.

  2. Click the View By drop-down list, located on the Process Management toolbar, and select Process Group.

    Note:
    View By Process Group is the default option when you open the Process Management window.

To view active processes by Process

  1. Open the Process Management window.

  2. Click the View By drop-down list, located on the Process Management toolbar, and select Process.


About Managing Active Processes

BPM Suite enables you to pause, stop, or restart a running BPM process. You can even edit a process while it is running. These functions are performed through the Process Management tool.

Managing Active Process Groups and Processes in Process Management

  • Restarting an Active Process or Process Group

  • Canceling an Active Process or Process Group

  • Pausing an Active Process or Process Group

  • Resuming an Active Process or Process Group

  • Editing an Active Process

  • Restarting Activities

  • Saving Process Images


Canceling an Active Process or Process Group

Canceling Active Processes

You can use the Process Management window to cancel an active process. You can also cancel all the processes and sub-processes in a Process Group if you are viewing processes by Process Group.

To cancel a triggered process

  1. Open the Process Management window.

    Note:
    If the process you are looking for did not start within the last month, you will have to adjust the date range.

  2. Select the process or process group you want to cancel from the process list in the left pane.

    Note:
    If you do not want to cancel all of the processes in a Process Group, expand the process tree-structure until you locate the process you want to cancel.

  3. Right-click the process you want to cancel and select Cancel Process.
    A window confirms the process has been cancelled.

Related Topics

About Managing Active Processes


Editing an Active Process

You can use the Process Management tool to edit an active process.

Example

You have a running process that will not complete because there is an error in the data someone submitted, or every logical branch evaluates to "False", or any other reason. You can modify only the instance of the process that is experiencing difficulty and make changes.

The changes you make to a running process affect only that process and will not be applied to any other running processes or processes that start after this process.

To modify an active process

  1. Open the Process Management window.

    Note:
    If the process you are looking for did not start within the last month, you will have to adjust the date range.

  2. Select the Process you want to modify from the list of processes in the left pane.

  3. Right-click the process you want to modify and select Edit this Process Instance.
    The process is paused and opens in a new window. The process is now in an editable state, similar to if you had opened the process through the Process Explorer.

    Important
    The changes you make to this process only affect the currently running instance. These changes will not be saved to the process template and will not affect any other past, current, or future instances of this process.

  4. Edit the process any way necessary (e.g. change the logical branches so that they can evaluate to "True".)

  5. Click the Save button after you have finished making changes.

  6. Close the process window.

  7. Right-click the same process instance and select Resume Process.
    The process resumes and uses the changes you made.


Opening the Process Management window

The Process Management window allows you to view and manage active processes.

To access the Property Management window

  1. Click the Process Management menu and select View/Manage Processes and Process Groups.
    The Process Management window opens with a list of active processes in the left pane.

    The upper right pane displays process information. The lower right pane displays the process image.

Note

You can update the list of running process and the process image by clicking the Refresh button in the upper-left corner of the Process Management window. You can also refresh the process image by pressing F5.


Pausing an Active Process or Process Group

You can use the Process Management tool to pause an active process or process group. You can also pause all the processes and sub-processes in a Process Group if you are viewing processes by Process Group.

To pause an active process

  1. Open the Process Management window.

    Note:
    If the process you are looking for did not start within the last month, you will have to adjust the date range.

  2. Select the Process or Process Group you want to pause from the list of processes in the left pane.

    Note:
    If you do not want to pause all of the processes in a Process Group, expand the process tree-structure until you locate the process you want to pause.

  3. Right-click the process group you want to pause and select Pause Process Group or right-click the process you want to pause and select Pause Process.
    A window confirms the process has been paused.


Restarting Activities

You can use the Process Management window to restart an activity.

To restart an activity

  1. Open the Process Management window.

    Note:
    If the process you are looking for did not start within the last month, you will have to adjust the date range.

  2. Select the process with the activity you want to restart from the list of processes in the left pane.

    Note:
    You may have to expand the tree-structure of processes to locate the process with the task you want to cancel.

  3. Click the activity you want to restart.
    Handles appear around the activity to indicate that it is selected.

  4. Right-click the activity you want to restart and select Restart Activity.
    A window confirms the activity has been restarted.

Related Topics

About Managing Active Processes


Restarting an Active Process or Process Group

You can use the Process Management window to restart an active process. You can also restart all the processes and sub-processes in a Process Group if you are viewing processes by Process Group.

To restart a triggered process

  1. Open the Process Management window.

    Note:
    If the process you are looking for did not start within the last month, you will have to adjust the date range.

  2. Select the Process or Process Group you want to restart from the list of processes in the left pane.

    Note:
    If you do not want to restart all of the processes in a Process Group, expand the process tree-structure until you locate the process you want to restart.

  3. Right-click the process you want to restart and select Restart Process.
    A window confirms the process has been restarted.

Related Topics

About Managing Active Processes


Resuming an Active Process or Process Group

You can use the Process Management tool to resume a process or process group that has been paused. You can also resume all the processes and sub-processes in a Process Group if you are viewing processes by Process Group.

To resume a paused process

  1. Open the Process Management window.

    Note:
    If the process you are looking for did not start within the last month, you will have to adjust the date range.

  2. Select the Process or Process Group you want to resume from the list of processes in the left pane.

    Note:
    If you do not want to resume all of the processes in a Process Group, expand the process tree-structure until you locate the process you want to resume.

  3. Right-click the process group you want to resume and select Resume Process Group or right-click the process you want to resume and select Resume Process.
    A window confirms the process has been resumed.


Saving Process Images

You can save the image of an active process, which you can open in Microsoft Word and share with other people in your organization who do not have access to BPM Designer.

To save a process image

  1. Open the Process Management window.

    Note:
    If the process you are looking for did not start within the last month, you will have to adjust the date range.

  2. Select the process that has an image you want to save from the list of processes in the left pane.

    Note:
    You may have to expand the tree-structure of processes to locate the process you want.

  3. Right-click the Process Management Canvas and select Save Process Image to File.
    The Save Process Image as Metafile window appears.

  4. Browse to the location that you want to save the image.

  5. Click Save.
    A window confirms the location of the save.

    Note:
    You cannot save the image with a *.gif, *.jpg, or other image file extension. Images must be saved as Metafiles.

  6. Click OK.
    You can now open the image in Microsoft Visio or Microsoft Office Picture Manager. You cannot open the image in Microsoft Paint.

Related Topics

About Managing Active Processes


About Testing and Monitoring Processes

Typically, the processes you design will start running as a result of someone using a Web form, a third party application (such as Microsoft CRM) or a Microsoft Office macro. However, you can start processes without leaving the Designer, which makes it easy to test processes before they have been implemented.

BPM Designer also provides a robust tool for monitoring active processes.

Testing and Monitoring Processes

  • Starting Test Processes

  • Viewing Properties of an Active Process

  • Viewing Properties of Activities in Active Processes

  • Filtering the Active Process List

  • Managing Active Processes

  • Status Colors for Processes and Activities

Demo Movies

Flash-based movie demos of BPM Designer can be accessed along with this User Guide. If you prefer to see some of the basic functions of BPM Designer as movies, these demos will introduce you quickly. Learn more about BPM Designer Demos.

Relevant Movies:

  • Initiating and Managing a Process


Setting Data Item Values When Starting a Process

When you open the Start Process window, Data Items that have Default Values should be automatically populated. However, if you want to, you can enter values for any of the Data Items.

If a Data Item has a Default Value, but you have entered a different value, you can force the Data Item to retake its Default Value.

Also, if you enter Data Item values that you plan to reuse, you can save the values to a Data Item Value (.div) file and load them again later.

Steps for all of these procedures are below.

To enter values for Data Items when you run a process

  1. Open the Start Process window, if you have not already done so.

  2. Locate the Data Item whose value you want to set and enter a value in the field next to it.

To force the default values to load

  1. Open the Start Process window, if you have not already done so.

  2. Click the Load Default Values button.
    The Data Items that have Default Values are populated with those values.

To save the values you have entered

  1. Open the Start Process window, if you have not already done so.

  2. Enter values for the Data Items

  3. Click the Save Data Item Value Settings button.
    A window allows you to choose where to save the Data Item Value file.

  4. Choose a location on your computer and click Save.
    You can now access that file to load those Data Item values whenever you need to.

To load Data Item values you have saved

  1. Open the Start Process window, if you have not already done so.

  2. Click the Load Data Item Value Settings button.
    A window allows you to select the Data Item Value file that contains your saved values.

  3. Select the file that contains your saved Data Item values.

  4. Click Open.
    Your Data Item values are automatically populated according to the .div file.

Related Topics

Starting Test Processes


Starting Test Processes

To test your processes, you can start the process from within the Process Designer. After starting a process, the process will appear in the Process Management window.

To start a test process

  1. Open the process you want to initiate.

    Note:
    The process must be saved before it can be started. If you have made any changes to your process since saving it last, save it and then you will be able to start the process.

  2. If necessary, set the Data Item values.

  3. Click the Start Process button.
    The Start Process window opens.

    Note:
    The Start Process window allows you to enter values for the Data Items in the process. To start a process, you do not need to enter values for any of the Data Items.

  4. Click the Start button.
    A window confirms the process was started.

  5. Click OK.
    The window closes. To view the running process, open Process Management.


Status Colors for Processes and Activities

Processes and activities have status colors associated to them. You can look at a processes in the left pane of the Process Management window to see its status color. You can also see the status color for an activity when a process is open.

  1. Open the Process Management window.

  2. Click the Show Color Key button [image].
    The Status Color Key window opens. Use this window as a reference while managing your processes.

Related topics

About Managing Active Processes


Viewing Properties of Activities in Active Processes

You can view Properties for activities in an active process at any time. The Properties for activities in an active process can provide information for testing, reporting, debugging, and more.

To view Properties for an activity in an active process

  1. Open the Process Management window and use the list of processes in the left pane to locate the active process you want to view.

  2. Click the + to the left of the active process.
    A folder labeled Processes appears below the active process.

  3. Click the + to the left of the Processes folder.
    The label you gave the process appears below the Processes folder.

  4. Click the process label.
    The process definition appears in the lower right pane.

  5. Double-click the activity with the properties you want to view.
    The Activity Properties window opens with four tabs: Activity Definition, Activity Status, Data Item Values, and Logging.

    Note:
    The Start and End nodes do not include the Logging tab.

  6. Browse the tabs to locate and review the information you need.

  7. When finished, close the window.

Related Topics

Viewing Properties of an Active Process


Viewing Properties of an Active Process

You can view the Properties of active processes at any time. The Properties for an active process can provide information for testing, reporting, debugging, and more.

To view properties for an active process

  1. Open the Process Management window and use the list of processes in the left pane to locate the active process you want to view.

  2. Click the + to the left of the active process.
    A folder labeled Processes appears below the active process.

  3. Click the + to the left of the Processes folder.
    The label you gave the process appears below the Processes folder.

  4. Click the process label.
    The process definition appears in the lower right pane.

  5. Right-click the Process Management Canvas and select Properties.
    The Process Properties window appears with three tabs: Process Definition, Logging, and Routing Log.

    Note:
    You can also open the Properties for an active process by double-clicking the Canvas.

  6. Browse the tabs to locate and review the information you need.

  7. Close the window when you are finished.

Related Topics

Viewing Properties of Activities in Activity Processes


About Business Analyst Setup

About User Setup

Some features of BPM Designer should be configured by Users before they begin to design processes.

You may not need to make changes to all these settings, but you should review them before you begin designing to make sure all the settings are complete and accurate.

Features that Need to be Configured

  • Changing Your User Password

  • Managing Default Notification Senders

  • Managing Notification Test Mode

  • Managing Test Recipients

  • Configuring the SQL Reporting Server URL

  • Configuring the Web Site Base URL

  • Managing Mail Server Properties

Optional Features You Can Configure

  • Configuring the Web Services URL for Starting Processes

  • Managing Cancelled Tasks

  • Managing Debug Settings

  • Managing Notification Types


Accessing the Options window

You can access the Options window using Tools menu.

To access the Options window

  • Click the Tools menu and select Options.
    The Options window appears.


Changing Your User Password

Changing Your Password

After logging in to BPM Designer for the first time with your default password, you should change your password so only you can access your information.

Note:
It's a good idea to change your password every 30 to 90 days, but follow your organizations policy for password specifications.

To change your User Password

  1. Click the Tools menu and select Change Password.
    The Change Password window opens.

  2. Enter your current password in the Old Password field.

  3. Enter your new password in the New Password field.

    Note:
    Passwords must be longer than six (6) characters.

  4. Enter your new password again in the Confirm New Password field.

  5. Click OK.
    A window asks if you want to confirm the password change.

  6. Click Yes.
    A window confirms that your password has been changed.

  7. Click OK.
    Your password is now changed.

Related Topics

About Business User Setup


Configuring the SQL Reporting Server URL (ReportServerURL Data Item)

On the Options window, you can set the value of the SQL Reporting Server global Data Item. The SQL Reporting Server Data Item identifies the server where Microsoft SQL Reporting Server is installed. BPM Web uses the URL you enter here to find the reporting server; when it is configured, the Reports tab will appear in BPM Web.

Note:
The SQL Reporting Server URL is not configured during the installation and must be configured manually for it to work. If the SQL Reporting Server URL is not configured, the Reports tab will not appear in BPM web.

To configure the SQL Reporting Server URL

  1. Open the Options window.

  2. Under the Server Properties tab, in SQL reporting server, type URL to the server where Microsoft SQL Reporting Server is installed.

    Example:
    http://ServerName/ReportServer

  3. Click OK.
    The Options window closes.


Configuring the Web Site Base URL (WebBaseURL Data Item)

On the Options window, you can set the value of the WebBaseURL global Data Item. The WebBaseURL Data Item is commonly used with Manual Activity notifications. The WebBaseURL Data Item value and Display Value are replaced with the value in the Web Site Base URL field on the Options tab.

Example:
In an Email notification, you could enter the following text, which would give users a direct link to their tasks screen in BPM Web:

%WebBaseURL.DisplayValue%/Tasks.aspx

Note:
The Web Base URL is not configured during the installation and must be configured manually for it to work.

To configure the BPM Web Site Base URL (WebBaseURL Data Item)

  1. Open the Options window and locate the BPM Web section on the Server Properties tab.

  2. Enter the URL to use as the base URL for BPM Web in the Web Site Base URL field.

    Example:
    http://BPMWebServer/bpmweb/bpm/

  3. Click OK to close the Options window.

Related Topics

About Business User Setup


Configuring Web Services URL for Starting Processes

The Web Services URL is used to start processes within the Process Designer. If the Bluespring Web Services URL is incorrect, you will not be able to start a process from within the Process Designer.

Note:
The Web Services URL is configured during the installation process and, by default, is set to the server running BPM Engine.

To configure the Bluespring Web Services URL

  1. Open the Options window, then click the Server Properties tab and locate the BPM Web section.

  2. Enter the Bluespring Web Services URL you want the current BPM Web Site to use in the Web Services URL field.

    Example:
    http://BPMSERVER/BluespringService/

    Note:
    The /Workflow.asmx extension is unnecessary and will be removed if you try to add it to the URL.

  3. Click OK to close the Options window.

Related Topics

About Business User Setup


Managing BPM Suite Options

BPM Suite contains many options that enable you to design processes more efficiently. By using default values located in the BPM Suite Options, the guess work is taken out of certain activities.

Managing Server Properties

  • Managing BPM Web Settings

  • Managing Mail Server Properties

  • Managing Cancelled Tasks

  • Managing Debug Settings

Managing Notification Options

  • Managing Notification Options

  • Managing Default Notification Senders

  • Managing Test Mode

  • Managing Test Recipients

Related topics

Accessing the Options window


Managing Cancelled Tasks

When a manual task is cancelled, the task remains in the user's task list. However, you can set how many days you want cancelled tasks to remain in a user's task list.

To change the number of days cancelled tasks appear in BPM Web

  1. Open the Options window and locate the Miscellaneous section on the Server Properties tab.

  2. Enter a number greater than or equal to zero (0) in the Number of days to display cancelled tasks field.

  3. Click OK to close the Options window.

Related Topics

About Business User Setup


Managing Debug Settings

When a process starts, BPM Suite records information about each step to help with debugging. This debug information is stored in the site's database. You can use the Process Management tool to view debugging information for a process and activities in a process.

Note: If you enable the system-wide debugging log, and your BPM system runs many processes with many activities, you may experience a decrease in system performance. To correct this, you can disable system-wide debugging (see "To disable debugging" below) and enable debugging for individual processes, as necessary.

You can also delete the debug log records to save space in the BPM database.

To enable debugging

  1. Open the Options window and locate the Miscellaneous section on the Server Properties tab.

  2. Verify that the Enable Debugging of Process Server Components check box is selected. If the option is not selected, select it now.

  3. Click OK to close the Options window.

To disable debugging

  1. Open the Options window and locate the Miscellaneous section on the Server Properties tab.

  2. Verify that the Enable Debugging of Process Server Components check box is not selected. If the option is selected, de-select it now.

  3. Click OK to close the Options window.

To clear the database debugging log

  1. Open the Options window and locate the Miscellaneous section on the Server Properties tab.

  2. Click the Clear Data button to delete the database debug data.
    A window confirms that the database debug data has been cleared.

    Note:
    By clearing the database debug data, you can save space on your server.

  3. Click OK to close the Options window.

Related Topics

About Business User Setup


Managing Default Notification Senders

BPM Suite enables you to enter a unique notification sender for each type notification: Email and SMS.

To set the default Email sender

  1. Open the Options window and click the Notification Options tab.

  2. Enter the email address of the default email sender in the Email field.

    Example:
    bpm@bpm.bluespringsoftware.com

  3. Click OK to close the Options window.

To set the default SMS sender

  1. Open the Options window and click the Notification Options tab.

  2. Enter the SMS name or ID of the default SMS sender in the SMS field.

  3. Click OK to close the Options window.

Related Topics

About Business User Setup


Managing Mail Server Properties

BPM Suite allows you to use a local or remote mail server to send and receive e-mail originating from your business processes.

To update Mail Server properties

  1. Open the Options window.

  2. On the Server Properties tab, locate the Mail servers section.

  3. Enter the name, IP, or URL of the SMTP server in the SMTP server field.

    Examples:
    BPMMAILSERVER
    172.0.0.1
    mail.bluespringsoftware.com

  4. Enter the Username by which e-mail messages will be sent in the Username field.

  5. Enter the password for the Username you entered in step 3 in the Password field.

  6. Enter the e-mail address of the network administrator in the Administrator Email Address box.

  7. Click OK.
    The Options window closes.

Related topics

About Business User Setup


Managing Notification Test Mode

BPM Suite can run in test mode or production mode. In test mode, all messages are sent to a single user, so the actual users defined in the process do not receive emails until the process is ready for production.

To enable notification test mode

  1. Open the Options window and click the Notification Options tab.

  2. Verify that the Enable Notification Test Mode option is selected. If it is not selected, select it now.

  3. Click OK to close the Options window.

To disable notification test mode

  1. Open the Options window and click the Notification Options tab.

  2. Verify that the Enable Notification Test Mode option is not selected. If it is selected, de-select it now.

  3. Click OK to close the Options window.

Related Topics

About Business User Setup


Managing Notification Types

BPM Suite allows you to notify Users that they have been assigned a manual task assignment via Email or SMS. Email cannot be disabled, and you can choose to enable SMS. If SMS is disabled, it will not appear in the Notification Options window when configuring a manual activity.

To enable SMS notification

  1. Open the Options window and click the Notification Options tab.

  2. Verify that the SMS options is selected. If it is not, select it now.

  3. Click OK to close the Options window.

To disable SMS notification

  1. Open the Options window and click the Notification Options tab.

  2. Verify that the SMS option is not selected. If it is selected, de-select it now.

  3. Click OK to close the Options window.

Related Topics

About Business User Setup


Managing Test Recipients

If BPM Suite is running in notification test mode, then all messages of the same type are sent to a single user.

Note:
If you do not configure the Test Recipient for a message type, then no notification will be sent during the test process.

To configure notification test recipients

  1. Open the Options window and click the Notification Options tab.

  2. Click the Test Recipients button.
    The Test Recipients window appears.

  3. Enter the test Email recipient in the E-mail field.

  4. Enter the test SMS recipient in the SMS field.

  5. Enter the test AOL Instant Messenger (AIM) recipient in the AIM field.

  6. Enter the test MSN Messenger recipient in the MSN field.

  7. Enter the test ICQ Messenger recipient in the ICQ field.

  8. Enter the test Yahoo Messenger recipient in the Yahoo field.

  9. Click Close to close the Test Recipients window.

  10. Click OK to close the Options window.

Related Topics

About Business User Setup


BPM Designer Demos

Flash-based movie demos of BPM Designer can be accessed along with this User Guide. If you want to become familiar with some of the basic functions in BPM Designer, these demos will introduce you quickly.

Demo Topics

  1. Process Designer Fundamentals
    • Create a New Process
    • Configure the Properties of a Process
    • Use the Activities Toolbox
    • Create Standard Links

  2. Create Lists, Values, and Data Items
    • Create Lists
    • Add Values to Lists
    • Create Data Items

  3. Managing Users and Roles
    • Create Users
    • Create Roles
    • Associate Users with Roles

  4. Using a Standard Manual Activity
    • Assign a Task to a Role and User
    • Set a Notification
    • Set an Escalation

  5. Initiating and Managing a Process
    • Initiate a Process
    • Use the Process Manager
    • Restart and Cancel a Process

To Access the Demos

  1. Click the Help menu and select Demos. A sub-menu appears.

  2. Click the name of the demo you want to watch.


Sorting List Items According to a Column in a Database Table

Type topic text here.


Understanding Activity Relationships

You can define parent and child relationships between BPM Activities.

Parent and child activity relationships

A parent activity is an activity from which other activities originate. A child activity is an activity to which other activities connect.

Activities are connected using standard links, logical expression links, and default links.

If you want to connect multiple activities to a single child activity, you will need to use a Connection Node. The Connection Node allows you to configure the process to continue after one or many parent activities complete. The Designer will automatically add a Connection Node to your process when you try to connect multiple parent activities to a child activity.

Related topics

Understanding BPM Activities


Understanding BPM Activities

BPM Activities represent common business tasks. BPM Suite has 31 activities that you can use to design your business processes.

Special Activities

Some activities have unique properties and are used to fulfill unique functions in a process design.

  • Start Activity
    The Start activity comes on the canvas of every process by default. It marks the beginning of the process and has no special properties tab.

  • End Activity
    The End activity comes on the canvas of every process by default. It marks the end of the process and has no special properties tab.

  • Connection Node
    The Connection Node is an automated activity that has unique properties. It is automatically inserted whenever you connect two or more activities to one activity. Because you are combining multiple process paths, which could finish at different times, the Connection Node defines when the process can continue (e.g. when one process path is complete, when two are complete, etc.)

Automated Activities

You can use Automated Activities to perform common business functions that use and manipulated information used in a process.

  • Connection Node

  • Calendar Delay

  • Command-line

  • Delay

  • GeoCoder

  • Get User Profile

  • InRule

  • Logical Expression Rules

  • Microsoft CRM 1.2

  • MSMQ Reader

  • MSMQ Writer

  • Multi-instance Sub-Process

  • Null Activity

  • Scripting

  • Set Data Items

  • Sub-Process

Database Activities

You can use Database Activities to manage information stored in a database.

  • SQL Executor

  • Table Reader

  • Table Writer

Desktop Activities

You can use Desktop Activities to communicate process information to business users through common desktop software.

  • Email

  • Excel Reader

  • Excel Writer

  • File Writer

  • InfoPath Form Reader

  • InfoPath Form Writer

  • PDF Form Reader

  • PDF Form Writer

  • Word Form Reader

  • Word Writer

Manual Activities

You can use Manual Activities when the process requires input from a business user.

  • Group Assign

  • Prior Manual Activity

  • Standard Manual

  • User Type Assignment

Web Activities

You can use Web Activities to transfer information over an Internet connection via either FTP, HTTP/HTTPS, or a Web service.

  • FTP

  • HTTP

  • HTTP Post

  • Web Service Invoker

XML Activities

You can use XML Activities to manage and manipulate information stored as XML.

  • Document Generator

  • Merge XML

  • Query By Example

  • XML Reader

  • XML Writer


Welcome to BPM Designer

User Guide

  • Administrator Setup

  • User Setup

  • Designing Processes

  • Configuring the Process Environment

  • Finding and Viewing Processes

  • Testing and Monitoring Processes

  • BPM Activities

Copyright 2006 Bluespring Software

All rights reserved.


Creating a List Using Values in a SharePoint List

When creating a list in BPM, you have the option of automatically populating it. If the information you want to add to the BPM list is in a list on a SharePoint site, you can read information from the SharePoint list to create your new BPM list.

To create a BPM list using values in a SharePoint List

  1. Open the List Management window, and then click the Add List Definition button [image].
    The Add New List window appears.

  2. Type a name for the list in the List Name box.
    The name of your list is also used for the Cache Filename.

    Optional    :
    Complete the list properties to perform any of the following actions:

    • Allowing Users to Add Information to a Look-Up List

    • Caching a List's Values on a Server

    • Allowing Only Administrators to Edit a List

  3. Click the List Location down arrow, and then click SharePoint List.
    The SharePoint List Options field appears.

  4. Click the SharePoint site URL down arrow, and then click the Web address that stores the list you want to use.

  5. In SharePoint user name, type the user name that has access to this site.

  6. In SharePoint password, type the password for the user name you entered in step 6.

    Optional:
    Select the SharePoint domain name option, and then type the value to specify the user's network (for example, if the user exists on more than one domain).

  7. Click the SharePoint list down arrow, and then click the list you wish to refer.
    Columns in this list appear in the Selected columns field.

  8. Select the SharePoint site columns in Selected columns that you wish to include in your new BPM list.
    All columns specified in SharePoint as viewable appear.

    Optional:

  9. Click Show hidden columns to expand the results of viewable SharePoint columns. This procedure does not change the inherent viewing status that is designated SharePoint.

  10. Click Filter items included in the list to enable the boxes in this filter group. In this group, you can specify conditions to meet before adding SharePoint list items to your BPM list.

  1. In Column to query, click the down arrow, and then click the desired item.
    In the next step, you will indicate how you wish to compare your Column to query selection to the SharePoint list item column value.

  2. In Type of comparison, click the down arrow, and then click a value.

  3. In Compare list item column value to, type the value to be used in the updated items query.

  9. Click OK.
    The Add New List window closes. Your list is created and populated with the values in the column(s) of the SharePoint list you specified.

Related Topics

Creating a List Using Values in a Base Content Database Table | Creating a Simple List | Creating a List Using Values in an External Database Table