Creating or modifying record instances using Record Service Tasks

According to the business logic that you want to create in a process flow, you might need to create or update record instances of record definitions that are used in a process. To perform operations, such as add, delete, or retrieve a record instance, you can use the Record Service Tasks in the Process designer.

For information about record instances, see Defining-record-definitions-to-store-and-manage-data.

Related topic

Defining-the-application-business-logic-through-processes

Types of Record Service Tasks

Record Service Task

Description

Create Record

A Create Record Service Task creates a record instance for a specified record definition. You create process parameters that can be mapped with the record definition fields. The values that you provide to the process parameters can be used to set record instance fields at the time of instance creation.

Update Record

An Update Record Service Task updates a record instance in a record definition based on a specific record instance ID. Specify the ID of the record instance that you want to update through a process parameter or through an expression.

Delete Record

A Delete Record Service Task deletes a record instance for a specified record definition. Specify the ID of the record instance that needs to be deleted through a process parameter or an expression.

Get Record

A Get Record Service Task retrieves a record instance from a record definition based on a specific record instance ID. Specify the ID of the record instance that you want to retrieve through a process parameter or an expression.

Get Attachment

A Get Attachment Service Task retrieves the attachments associated with a specific record definition.

Get Records By Query

A Get Records By Query Service Task retrieves record instances from a record definition based on the specified query.

Get Security Label

A Get Security Label Service Task retrieves a security label from a record definition based on a specific record instance ID. Specify the ID of the record instance that you want to retrieve through a process parameter or through an expression.

Remove Security Label

Important: The Remove Security Label element has been deprecated. We recommend that you use the Create Record and Update Record elements. 

A Remove Security Label Service Task deletes a security label for a specified record definition. Specify the ID of the record instance that needs to be deleted through a process parameter or through an expression.

To confirm whether the security label is updated, see Identifying updates to the security label.

Set Security Label

Important: The Set Security Label element has been deprecated. We recommend that you use the Create Record and Update Record elements. 

A Set Security Label Service Task sets the security labels (enables row-level security of record instances) through a process.

To confirm whether the security label is updated, see Identifying updates to the security label.

To add Record Service Tasks to processes

  1. Log in to BMC Helix Innovation Studio and navigate to the Workspace tab.
  2. Select the application in which your process exists.
  3. In the application, click the Processes tab.
  4. Click the process name that you want to modify to create record instances, delete record instances, retrieve record instance details, retrieve security labels, delete security labels, set security labels, or update record instances.
    The system opens Process designer and displays the process diagram on the canvas.
  5. Drag the appropriate Record Service Task to the canvas according to the operation you want to perform.
  1. Enter the required properties of the Record Service Task; see Record Service Task properties.
  2. Click Save.

Important

When using the output value of a Record Service Task as the input for an approval process, do not assign the output value directly. You must first assign the output value to a record-type process variable and then assign the process variable as an input to the approval process. This restriction does not apply to the Create Record Service Task.

Record Service Task properties

The following tables provide information about Record Service Task properties. For information about the common Service Task properties, such as Run as, or Multi instance loop, see Service Task properties.

Create Record properties

Property

Description

Record Definition Name

Record definition for which you want to create a record instance. You can select a record definition by using one of the following methods:

  • Select Record Definition—Select a record definition from the current application.
  • Build Expression—Build an expression to leverage a record definition dynamically at runtime.

Sample Record Definition Name

Record definition template that you use to create the record definition that you select at runtime.

The sample record definition fields are displayed in the Expression Editor that you can use to create an expression.

This option is displayed only if you select Build Expression from the Record Definition Name field.

Add/Remove Input Map Fields

Fields of the record definition that map to the process parameters or to an expression that assigns a value to the mapped fields. The new record instance is created using the values assigned to the mapped fields.

OUTPUT MAP

Process parameters that you want to obtain as output values from this Create Record Service Task. You can build an expression for assigning an output value to a process parameter.

For an example of the Create Record Service Task, see Pushing field values to other record instances.

Update Record properties

Property

Description

Record Source

Source of the record: database or process variable.

Record

Record instance, available only if the record source is a process variable.

Record Definition Name

Record definition for which you want to update a record instance. You can select a record definition by using one of the following methods:

  • Select Record Definition—Select a record definition from the current application.
  • Build Expression—Build an expression to leverage a record definition dynamically at runtime.

Sample Record Definition Name

Record definition template that you use to update the record definition that you select at runtime.

The sample record definition fields are displayed in the Expression Editor that you can use to create an expression. 

This option is displayed only if you select Build Expression from the Record Definition Name field.

Record ID

ID of the record to which you want to restrict access, available only if the record source is in the database. 

Add/Remove Input Map Fields

Property that maps the fields of the record definition to the process parameters or to an expression that assigns a value to the mapped fields. The record instance is updated using the values assigned to the mapped fields.

For an example of the Update Record Service Task, see Updating the current record instance using field values from another record instance.

Delete Record properties

Property

Description

Record Definition Name

Record definition for which you want to delete the record instance. You can select a record definition by using one of the following methods:

  • Select Record Definition—Select a record definition from the current application.
  • Build Expression—Build an expression to leverage a record definition dynamically at runtime.

Sample Record Definition Name

Record definition template that you use to delete the record definition that you select at runtime.

The sample record definition fields are displayed in the Expression Editor that you can use to create an expression. 

This option is displayed only if you select Build Expression from the Record Definition Name field.

Record ID

ID of the record instance that you want to delete. You can provide the ID through a process parameter or through an expression.

Get Record properties

Property

Description

Record Definition Name

Record definition for which you want to get the record properties. You can select a record definition by using one of the following methods:

  • Select Record Definition—Select a record definition from the current application.
  • Build Expression—Build an expression to leverage a record definition dynamically at runtime.

Sample Record Definition Name

Record definition template that you use to create record instances for the record definition that you select at runtime.

The sample record definition fields are displayed in the Expression Editor that you can use to create an expression. 

This option is displayed only if you select Build Expression from the Record Definition Name field.

Record ID

ID of the record instance that you want to retrieve. You can provide the ID through a process parameter or through an expression.

OUTPUT MAP

Process parameters that you want to obtain as output values from this Get Record Service Task. You can build an expression for assigning an output value to a process parameter.

Get Records By Query properties

Property

Description

Record Definition Name

Record definition for which you want to update the current record instance with field values from another record instance. You can select a record definition by using one of the following methods:

  • Select Record Definition—Select a record definition from the current application.
  • Build Expression—Build an expression to leverage a record definition dynamically at runtime.

Sample Record Definition Name

Record definition template that you use to retrieve record instances for the record definition that you select at runtime.

The sample record definition fields are displayed in the Expression Editor that you can use to create an expression. 

This option is displayed only if you select Build Expression from the Record Definition Name field.

Query Expression

Query expression to retrieve record instances.

Add/Remove Input Map Fields

Fields of the record definition that map to the process parameters or to an expression that assigns a value to the mapped fields. The new record instance is created using the values assigned to the mapped fields.

Retrieve

Property you can select to retrieve the first matching record or retrieve all matching records based on the query.

OUTPUT MAP

Process parameters that you want to obtain as output values from this Get Records By Query Service Task. You can build an expression for assigning an output value to a process parameter.

Get Security Label properties

Property

Description

Record Source

Source of the record: database or process variable.
 

Record Definition Name

Record definition for which you want to create a record instance. You can select a record definition by using one of the following methods:

  • Select Record Definition—Select a record definition from the current application.
  • Build Expression—Build an expression to leverage a record definition dynamically at runtime.

Sample Record Definition Name

Record definition template that you use to retrieve a security label from a record definition that you select at runtime.

The sample record definition fields are displayed in the Expression Editor that you can use to create an expression. 

This option is displayed only if you select Build Expression from the Record Definition Name field.

Record ID

ID of the record instance for which you want to retrieve security label details. You can provide the ID through a process parameter or through an expression.

Security label

List of security labels as defined in the record definition.

OUTPUT MAP

Process parameters that you want to obtain as output values from this Get Security Label Service Task. You can build an expression for assigning an output value to a process parameter.

The Get Security Label returns three output parameters:

  • Group—Comma-separated list of group names that are granted access. 
  • User—Comma-separated list of user names that are granted access.
  • Role—Comma-separated list of application role names that are granted access. The role names are displayed in the following format:
    <fully qualified application name>:<role name>

Set Security Label properties

Important: The Set Security Label element has been deprecated. We recommend that you use the Create Record and Update Record elements. 

Property

Description

Record Source

Source of the record: database or process variable.

Record

Record instance, available only if the record source is a process variable.

Record Definition Name

Record definition for which you want to grant row-level access to create and update record instances by adding security labels. You can select a record definition by using one of the following methods:

  • Select Record Definition—Select a record definition from the current application.
  • Build Expression—Build an expression to leverage a record definition dynamically at runtime.

Sample Record Definition Name

Record definition template that you use to sets the security labels for the record definition that you select at runtime.

The sample record definition fields are displayed in the Expression Editor that you can use to create an expression. 

This option is displayed only if you select Build Expression from the Record Definition Name field.

Record ID

ID of the record to which you want to restrict access, available only if the record source is in the database.  

Security Label

List of security labels as defined in the record definition.  

Group Names

Comma-separated list of group names to which you want to grant access. 

User Names

Comma-separated list of user names to which you want to grant access.

Role Names

Comma-separated list of fully qualified role names to which you want to grant access. If the application name is not identified, the application of the record definition is used instead.
Format: <fully qualified application name>:<role name>
For example:

com.bmc.arsys.taskmanager:Task

Viewer,com.bmc.arsys.casemanagement:Case Agent

Organization Ids

Comma-separated list of organization IDs to which you want to grant access.

Remove Security Label properties

Important: The Remove Security Label element has been deprecated. We recommend that you use the Create Record and Update Record elements. 

Property

Description

Record Definition Name

Record definition for which you want to remove row-level access to create and update record instances. You can select a record definition by using one of the following methods:

  • Select Record Definition—Select a record definition from the current application.
  • Build Expression—Build an expression to leverage a record definition dynamically at runtime.

Sample Record Definition Name

Record definition template that you use to delete a security label for the record definition that you select at runtime.

The sample record definition fields are displayed in the Expression Editor that you can use to create an expression. 

This option is displayed only if you select Build Expression from the Record Definition Name field.

Record ID

ID of the record instance for which you want to delete a security label. You can provide the ID through a process parameter or through an expression.

Security Label

List of security labels as defined in the record definition. 

Group Names

Comma-separated list of group names to which you want to revoke access.

User Names

Comma-separated list of user names to which you want to revoke access.

Role Names

Comma-separated list of application role names to which you want to revoke access.

Organization Ids

Comma-separated list or organization IDs to which you want to revoke access.

Example: Identifying updates to the security label

The Set Security Label and Remove Security Label elements have been deprecated. We recommend that you use the Create Record and Update Record elements. 

Security labels are used to enable the row-level security and define a series of users, groups, or application roles that can be given access to record instances by using a rule or a process. For more information, see Security labels. To identify whether there is an update to the security label made by Set Security Label or Remove Security Label actions, after the associated record instance is updated, you can use the SECURITYLABELCHNG() function.

The SECURITYLABELCHNG() function is used in a rule or a process. This function returns 1 if the security label of the current record is updated for the current transaction and returns 0 if the security label is not updated.

When using SECURITYLABELCHNG() function in a process, ensure that you add a record instance as a parameter. When using SECURITYLABELCHNG() function in a rule, you do not need to add any parameters.

The following image illustrates a sample process to check whether the security label of a case record is updated if the assignee is from a different support group. If the security label is updated, trigger the process to make changes to the related tasks. 

22_1_Security label process image.png

Important

If you have a wait state in the process, for example, User Task or Receive Task, the SECURITYLABELCHNG() function returns 0 even if the security label is changed.

Example: Creating or updating record instance

To create a new record instance or to update a record instance, use Create Record or Update Record Service Tasks respectively.

  • To find record instances that need updating, use the Get Records By Query action type and to loop through all records, use the Update Record action type. 
  • If you want to create record instances and do not finding any matching records, use a gateway to do a null check of the output of Get Records By Query.
  • If you want to update only one record instance, you can optimize Get Records By Query by retrieving only the first matching record instance, and update only that first record instance without using the loop.
    In Get Records By Query, select only those fields that are needed by the process, which simplifies the activity result.

The following image illustrates a sample process:

22_1_CreateUpdateRecord.PNG

The following images show sample configurations of steps for Find the Company, Update Company Record, and the No branch of the Found the Company gateway for the above process:

Process steps

Sample configuration

Find the company

221_GetRecordsbyQuery.png

Update Company Record

221_Update Record.png

Found the Company

22_1_Condition.PNG

Example: Updating the current record instance by using field values from another record instance

You can update the current record instance with field values from another record instance by using Get Records By Query and Update Record. To find the record instance from which you want to use the field values, use Get Records By Query. To set field values of the current record instance, use Update Record.

In Get Records By Query, select only those fields that are needed by the process, which simplifies the activity result and retrieves only the first matching record.

The following image illustrates a sample process:

22_1_SetFieldFromForm.PNG

The following images illustrate sample configurations of process variable and process steps for the above process: 

Process step

Sample configuration

Process variable

22_1_ProcessVariable.PNG

Find Customer Name

221_Find Customer name.png

Set Customer Name on Task

22_1_SetCustomerName.PNG

In Set Customer Name on Task, the name is22_1_customerName.png

Example: Updating a transaction value using process and rule

The transaction value references the value of the field in the current transaction only. When you create or update a record instance for business applications, you might be required to validate and update the record instance before storing it in the database. In BMC Helix Innovation Studio, a rule has a trigger that is activated on record events. We recommend that the rule calls a process to perform an action. In the Rule designer, the transaction value is represented by using the Current Record ($ENTRY$) keyword.

To update the transaction record instance through a process, use the Update Record Service Task and select the following parameters:

  • Record Source—Process Variable
  • Record the transaction record instance

The following images illustrates a sample configuration to update the transaction record:

Action

Sample configuration

Rule Start Process

22_1_Rule Start Process.png

Process Input Parameter

22_1_RecordInput.png

Update process variable (task) using Update Record Service Task

22_1_Update_process_variable_task.png

  • To enable the sample record definition feature, in the Process designer Process Properties pane, navigate to Add/Remove Variables, select the Data Type as Record and select the Use Sample Data check box and then select the sample record definition.
  • To share a process with different record definitions and to associate a record data type to more than one record definition, you can use a sample record definition, where a process can refer to fields of different record definitions. However, the process does not validate the record definition name at runtime. If the record instance does not have a field referenced by the process, a null value is returned.
  • We recommend that record definitions that share the same process definition be inherited from a common base record definition. Record inheritance ensures that all the fields referenced in a process definition are available to all inherited record definitions. For more information about record inheritance, see Inheriting-an-existing-record-definition-to-a-new-record-definition.