The following sections provide guidelines for good usage.
Orchestration Workflows
Best practices for orchestration workflow usage follow:
- Limit the data that is passed into the workflow to improve the
performance of both asynchronous and synchronous workflows. By default, all
fields in the primary table are passed to an aynchronous orchestration
workflow; you can reduce this by clearing the check boxes for unnecessary
fields in the Orchestration Link in the application. For synchronous workflows,
you can choose both inputs and outputs in the Orchestration Link; select only
those fields that are needed. (See
About Orchestration Links
for information about orchestration links.)
CAUTION:
Do not limit the fields that are passed to the
workflow if it means that you will later have to retrieve the field data with a
Web service call in a
Service step. The overhead of the Web
service call is greater than any benefit gained by limiting the fields.
- If a Web service returns a large amount of data in the response,
the entire body of data is loaded into memory, which can cause performance
problems. Instead of requesting the entire body of data in a single call,
consider breaking it into smaller pieces. For example, instead of using a "get"
operation on 100 items, create a loop that gets information for twenty items at
a time. You also throttle on payload size. For information about this, see the
"Scaling Orchestrations" white paper. To access this white paper, go to
http://www.serena.com/support
and then search for the S136965 solution.
- Use asynchronous (not synchronous) orchestration workflows to:
- Update or insert data, especially on external systems
- Call Web services that can take a long time, because
synchronous orchestration workflows can time out.
Synchronous orchestration workflows should only be used if the
user must see the result of a transition immediately, and only to validate data
the user entered or populate fields on a form.
- If a Web service throws a number of SOAP faults, use separate fault
handlers for each fault. This reduces the complexity of the fault handlers;
makes the workflow design clean and concise; and reduces the size of the
workflow, which makes it more scalable.
- Check for an existing item in an "update" workflow and end the
workflow if the item does not exist. Similarly, check for an existing item in a
"create" workflow and end the workflow if the the item exists. This makes your
orchestration handle error cases gracefully.
- When an orchestration workflow or Web service call updates an
external tool, that tool could, in response to the update, raise an event in
SBM
to synchronize the change. Because the change originated in
SBM,
the event can be ignored. For example, suppose there are two users: "SBMUser"
and "ExternalUser." "SBMUser" updates an
SBM
item, and the
Last Modifier field value is "SBMUser." The connector
replicates the item in the external tool using "ExternalUser," which
automatically raises an event that is sent to
SBM.
In this case, the event should be ignored and the workflow should end.
- When implementing integrations between
SBM
and an external tool, use a dedicated
SBM
user and a dedicated external system user for updating items in the external
system. This can prevent unintended permission errors during the execution of
the orchestration workflow.
- Use references between items in
SBM
and an external tool. For example, external tools should contain a field to
hold the
SBM
item ID. This allows workflows to easily identify the target
SBM
item and know if one has been created yet. On the other hand, the
SBM
item should have a unique identifier field to hold a reference to an item in
the external tool. This could be two fields, such as
Database Name and
Item ID.
-
If data is the same among
SBM
environments, create a working data element to hold the data. If the data is
different among environments, store the data in auxiliary tables and retrieve
the information dynamically depending on the situation. The following items
describe this principle in more detail, using authentication data as an
example.
- In a connector scenario, authentication data is likely to be
the same for different environments (such as Development, Testing, and
Production). Normally, if you are using
SBM
Web services, no authentication credentials are needed; however, you can
hard-code a designated user in the
SBM
Web services auth element to override the calling user if the permissions for
the calling user are not adequate. Make sure that the overriding user has all
of the permissions the workflow needs (for example, permission to read table
data, update items, and so on). If you need to override the calling user,
create working data elements to hold and store the authentication data for the
SBM
user.
- In a direct
SBM-to-external
tool scenario, the authentication data for users can be different among
environments. By default, the workflow runs in the context of who invoked it.
It is a good practice to store the authentication data for each user in an
auxiliary table. The orchestration workflow queries the data based on the user
and then stores it in working data elements.
Whether the user name and password are stored in working data or
in an auxiliary table depends on the following:
- Whether the authentication data might need to be modified by an
administrator in the auxiliary table. Modifications could be needed if the
authentication data is different among environments or if the company policy is
to change the data regularly. If this data is stored in working data, it is
more difficult to change and requires redeploying the process app.
- Whether there are policies concerning where sensitive data like
user names and passwords are stored. For example, you might not want developers
to have access to the user name and password for the payroll system.
Because access to auxiliary tables require a set of permissions,
you might need to put the
SBM
user name and password in the working data. To keep this information private,
you can use HTTPS for your Web service calls.
- If you are calling a Web service from an orchestration, and the
call requires a certificate for authentication, ensure that your certificate
contains the
clientAuth property if it is required. For example:
#8: ObjectId: 1.2.29.37 Criticality=false
ExtendedKeyUsages [
1.2.3.1.5.5.8.2.2
clientAuth
serverAuth
]
Steps
Best practices for step usage follow:
Step Functions
The expressions used in
Calculate,
ForEach, and
While steps can contain a variety of
Supported XPath Functions.
Best practices for step function usage follow:
- Use the
NUMBER function to convert text to integers. Use the
STRING function to convert integers to text.
- The
CONCAT function supports the concatenation of any
number of arguments. When you use the
CONCAT function, provide all arguments in a single
call to build a text string; do not use nested
CONCAT calls.
- Use the
STRINGLENGTH function to determine if a text element
is empty or has data. For example, use
STRINGLENGTH(SomeElement) = 0 instead of
SomeElement = "" and STRINGLENGTH(SomeElement) >
0 to determine whether a text element contains data.
- When you test for a negative (does not contain), use the
NOT function to turn a branch into a positive. For
example, use
NOT(CONTAINS(SomeText, "some string")) for a
branch that is taken when the
SomeText element does not contain "some string."
Working Data Elements
Best practices for working data element usage follow:
- If you have a common set of data that is used in multiple places in
the workflow (for example, authentication credentials), create working data
elements that store the data in one place, instead of setting the data as
default values in every
Service step. You can then map the working
data to the authentication inputs for the steps. If you need to change the
credentials later, you can do it in working data one time, instead of in each
step.
Important: If the values differ among environments, store
the data in an auxiliary table and query the table to populate the working data
at the beginning of the orchestration workflow.
- Use library types for elements where applicable. For example, use
the the
sbmappservices72
auth type instead of separate data elements for
userId and
password. This lets you map one working data element
to one
Service step data element instead of two.
Note: To use library types, right-click a new working data element,
select
Type, select
Select from Type Library, and then select
the type from the
Select Library Type Dialog Box.
- Store
SBM
itemID inputs as text, because the
sbmappservices72 operations all expect text
values.
- Provide working data elements to store intermediate data extracted
from array elements. For example, use
ItemProductBacklog to store:
SBM_GetItem.GetItemResponse.return.item.extendedField
→[id.dbName="PRODUCT_BACKLOG"].value[internalValue]
- Generally, you will use quotes to surround string constants in
working data variables. When working with string constants that contain
quotation marks, use either single or double quotes to surround string
constants, depending on the type of quotation mark in the string. For example,
to insert a single quote, surround the string constant with double quotes. To
insert a double quote, surround the string constant with single quotes. If you
do not need to specify either type of quote in the content, you can use either
single or double quotes to surround the string constant.
Web Services
SBM
includes two Web services that provide numerous operations:
sbmappservices72 and
sbmadminservices72. Best practices for Web
service usage follow:
- Never use both display names and interval values. The display name
is what the user sees and the internal value is what is stored in the database.
For text fields these are the same, but for many field types they are
completely different. Setting the display name and internal value to the same
value will prevent the field from being updated.
For example:
- A
Selection field's display name could be
High, but its internal value could be
13 (the ID of the record in the
TS_SELECTIONS table.)
- A transition's display value could be
Delegate, but its internal value could be
WorkflowName.Delegate.
- Make sure the values for
Selection,
Relational,
User, and
Group fields (Single and
Multi-) in
SBM
and the external tool match exactly. For example, if the display value is used
in one, make sure the display value, not the internal value, is used in the
other. In
Multi-Relational fields, use arrays to use display values or
internal values consistently.
- When you need to create and assign values to extended fields,
create the array elements directly in the
Service steps and assign values to them
directly, instead of trying to dynamically create them.
- The
createDate and
createdBy data elements represent the
Submit Date and
Submitter fields in the item. (The
SBM
Web services use these data element names instead of the database field names.)
- Orchestrations are not intended to be used to process very large
blocks of data or file attachments. For example, the
sbmappservices72 GetFileAttachment call
enables you to retrieve file attachments for a given item; however, you should
avoid using this call in an orchestration because orchestrations are not
designed to handle this kind of data efficiently. If this is unavoidable in
your application,
Serena
recommends that you set the attachment element in the response message to an
empty string as soon as the reason for bringing the attachment into the
orchestration has been satisfied before the orchestration finishes. This frees
the attachment data block and should allow the system to recycle the memory.
Otherwise, the
Orchestration Engine
will persist the attachment to the Orchestration Engine database as part of the
response message. This can cause orchestration processing to take a long time
and cause unnecessary space to be allocated in the
Orchestration Engine
database.
Note: See the
SBM Web Services Developer's
Guide
for detailed usage information and best practices for each operation.
Copyright © 2007–2015 Serena Software, Inc. All rights reserved.