Lock Service

The Lock service enables a business process to request, renew, or delete a lock for a particular resource.

The Lock service enables a business process to request, renew, or delete a lock for a particular resource. The following table provides an overview of the Lock service:

System Name	LockService
Graphical Process Modeler (GPM) category	All Services
Description	Enables a business process to request, renew, or delete a lock for a particular resource.
Business usage	If you have a business process, or resources within a business process, that should never have more than one instance running at a time, you can use the Lock service to prevent other instances of the business process, or just a certain part of the business process, from running until the lock is released.
Usage example	You have a business process that uses a configuration of the File System adapter called “Inbound Invoices.” To prevent this particular configuration of the File System adapter from being invoked by another business process while processing data in the current business process, you add the Lock service before the File System adapter in the business process, to lock that resource. You add a second instance of the Lock service after the File System adapter in the business process to release the lock once the File System adapter processing is complete.
Preconfigured?	Yes
Requires third-party files?	No
Platform availability	All supported Sterling B2B Integrator platforms
Related services	None
Application requirements	None
Initiates business processes?	No
Invocation	As part of a business process.
Business process context considerations	None
Returned status values	Returned status values: Success Error
Restrictions	None
Testing considerations	Use the Business Process Example as a test.
Supports Transactional Processing?	Yes

How the Lock Service Works

The Lock service secures a business process and prevents other business processes from using the locked resources until the lock is released. The Lock service uses the lock key and duration time that you set in the GPM for the business process to identify the lock to set and how long to keep the resources locked. You can lock all of the activities and services used in a business process by adding the Lock service to the beginning of a business process after the Start and Sequence Start activities. Or, you can lock just some of the activities or services in a business process by adding the Lock service directly before the activities or services to be locked.

To release the lock, add another instance of the Lock service to the business process directly after the group of locked activities and services. If the entire business process was locked, add the second Lock service to the end of the business process, directly before the End Sequence and End activities.

Implementing the Lock Service

To implement the Lock service, complete the following tasks:

Create a configuration of the Lock service, or use the configuration installed with the Sterling B2B Integrator, LockService. See Managing Services and Adapters. For information about the fields specific to this service, see Configuring the Lock Service.
Include two instances of the Lock service in your business process (one to lock resources, another to unlock them).
Specify field settings for each instance in the GPM as necessary. Ensure that you set the first instance to use the Lock action, and the second to use the Unlock action. Also ensure that you specify the same lock key for both.

Configuring the Lock Service

Use the field definitions in the following table to set up the service configuration in the GPM:

Field	Description
Config	Select the name of the service configuration from the list.
ACTION	Action performed for the requested lock. Valid values are: Check – Looks for the existence of a lock that is identified in the LOCK_KEY field. If the lock exists, the LOCK_EXIST output workflow parameter is set to true. If the lock does not exist, LOCK_EXIST is set to false. Lock – Create (default). List Locks - Returns a document containing an XML list of details for the current active locks. Touch – Renew. Unlock – Delete. Optional. Note: As a best practice, always use the Lock service in pairs in your business processes—one instance to lock the business process, and one to unlock the business process after the necessary operations have completed.
DURATION	Time, in milliseconds, that the lock is applied. Required. The lock will time out or expire after this time. Note: If a business process halts due to an error, the service configuration will remain locked until you manually release the lock or restart the Sterling B2B Integrator.
LOCK_KEY	The key for obtaining the lock. Required. If using two instances of the Lock service in the same business process (one to lock, the other to unlock), this key must be the same value for both.
USER	User name associated with the lock (informational only). Optional. If using two instances of the Lock service in the same business process (one to lock, the other to unlock), this key must be the same value for both.

Parameters That Must be Added in BPML

The following additional parameters can be used with Lock service by editing the BPML:

Parameter	Description
CLEAR_ON_START_UP	Clears the lock after you restart the Sterling B2B Integrator. Use when you want to ensure that the lock is always clean when the Sterling B2B Integrator is restarted. Optional. Valid values are true and false.
IN_TRANSACTION	Determines whether Lock service can participate in multi-step transactions. Optional. Default is false. Valid values are: True - Forces Lock service to participate in multi-step transactions. False - Lock service does not participate in multi-step transactions. Data base will not roll back. In cases where changes are immediately visible to other business processes, this should be false.

Business Process Example

The following example illustrates how the Lock service could be used in a business process.

In this business process, a lock is applied by the Lock service. The lock is set to a duration of 600,000 milliseconds, and uses “Lock1” as the lock key. In this business process, the resource being locked is an instance of the Sleep service. Note that the sleep interval (duration) is 45 seconds. The Sleep service is followed by a second instance of the Lock service that releases the lock, thereby freeing up this configuration of the Sleep service configuration for other processes.

Note: The business process also includes onFault activities and messages in the event that one of the lock activities fails.

<process name="LockExample">
  <sequence name="Start">
    <operation name="SetLock">
      <participant name="LockService"/>
      <output message="Xout">
        <assign to="DURATION">600000</assign>
        <assign to="LOCK_KEY">Lock1</assign>
        <assign to="CLEAR_ON_START_UP">true</assign>
        <assign to="." from="*"></assign>
      </output>
      <input message="Xin">
        <assign to="." from="*"></assign>
      </input>
    </operation>
    <sequence name="Process">
      <operation name="Sleep">
        <participant name="TestSleepService"/>
        <output message="Xout">
          <assign to="SLEEP_INTERVAL">45</assign>
          <assign to="." from="*"></assign>
        </output>
        <input message="Xin">
          <assign to="." from="*"></assign>
        </input>
      </operation>
      <sequence name="UnLock">
        <operation name="UnLock">
          <participant name="LockService"/>
          <output message="Xout">
            <assign to="ACTION">unlock</assign>
            <assign to="LOCK_KEY">Lock1</assign>
            <assign to="." from="*"></assign>
          </output>
          <input message="Xin">
            <assign to="." from="*"></assign>
          </input>
        </operation>
        <onFault>
          <assign to="UnLock_Msg" append="true">Failed to obtain an 
              unlock!</assign>
        </onFault>
      </sequence>
      <onFault>
        <operation>
          <participant name="LockService"/>
          <output message="Xout">
            <assign to="ACTION">unlock</assign>
            <assign to="LOCK_KEY">Lock1</assign>
            <assign to="." from="*"></assign>
          </output>
          <input message="Xin">
            <assign to="." from="*"></assign>
          </input>
        </operation>
      </onFault>
    </sequence>
    <onFault>
      <assign to="Lock_Msg" append="true">Failed to obtain a lock!</assign>
    </onFault>
  </sequence> 
</process>

The following GPM screen shows the example business process graphically. Note that the instance of the Lock service called SetLock is selected and its properties are displayed in the Service Editor in the lower half of the screen:

Lock Service – Frequently Asked Questions

How do I determine what the duration of a lock should be?

Set the lock duration value carefully (generally 2-3 times what the estimated time of execution will be) so that lock does not time out before the business process reaches the unlock step.

If the lock or unlock step fails (or any step in the business process between the two Lock services), are there any “cleanup” activities that need to be done?

Halted business processes can be terminated, or they can be left in halted state until the issue is resolved, and then restarted or resumed (as appropriate for the persistence level). The path to take depends on the needs of your business with regard to the business process itself. For example, is it mission-critical? Do other processes depend on its completion? Is the locked resource going to cause other business processes that use it to halt? Was the error caused by a problem in the configuration of the locked resource? Will this need to be corrected before using it again?

There are two general steps to follow first:

Check the lock manager page to see what's locked.
Check Business Process > BP Monitor > Current Processes for more information about the error.

Then, once you have determined what caused the error, you can decide when to release the lock and when to terminate, restart, or resume the business process.

To manually release a locked resource:

Go to Operations > Lock Manager, and click Go! in the List panel. The locked resources are displayed on a results page. Locate the resources from your business process that are locked and clear the Lock checkbox for the resources.

To terminate, restart, or resume a business process:

Go to Business Process > Monitor > Current Processes and select the ID of the halted instance of your business process. From the page displayed, you can select the appropriate action for this business process: terminate, restart, or resume.

Are there any best practices for using the Lock service in a business process?

Use the Lock service twice in a business process—one to lock resources and one to unlock them. The first instance precedes the resources to be locked and the second instance follows them. See the Business Process Example for a graphical representation. Do not use just one instance of the Lock service in a business process and let it expire instead of using a second Lock service to release the lock.