Usage

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:

Use ForEach steps to always process every item in an array element.
Use While steps to process an item only if a certain condition exists before entering the loop and while in the loop.
Use Calculate steps to perform manipulations such as string concatenation and data conversion. You can also use Calculate steps to store intermediate data that needs to be extracted from previous Service steps or events in the workflow, as described below.
Use Calculate steps to extract a specific element from an array of elements. The most common use is to extract a specific field from the extendedField of a response from a "GetItem" operation. For example:
```
SBM_GetItemResponse:SBM_GetItem.GetItemResponse.return.item.extendedField
→[id.dbName="PRODUCT_BACKLOG"].value[internalValue]
```
Do not use Calculate steps to transform large amounts of data because it requires a large number of Calculate steps. It is better to use a Web service to do this.
Use only the number of Calculate steps that you need. Excessive Calculate steps can slow orchestration workflow processing.
If you use several Calculate steps to achieve a single result (such as transforming one data structure into another), group those steps into a Group step and give it a name that describes the transformation.
Do not use working data elements to store data that can be mapped directly from the outputs of a previous Service step to the inputs of a subsequent Service step. For example, the ItemId of an SBM_GetItem Service step can be mapped directly as an input to an SBM_UpdateItem Service step.
Consider using the main branches from a Decision step to handle expected use cases, and reserving the Otherwise branch for errors where none of the expected cases occur.
Use Scope steps to create a structure that handles faults that occur during the execution of a Web service.
Use Group steps to organize steps that together perform a larger set of logic.

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.