Using block jobs in the Order Blotter dashboard

LUSID allows you to create your own custom actions to perform on one or more order blocks in the Order Blotter. For example, you could create a block job that runs some data validation, or sends blocks to an external process.

You define these custom block jobs using Luminesce custom views. Once you have created a custom view, you can select it as Block job when interacting with the Order Blotter in the LUSID web app:

The block job is a Luminesce custom view which must take in a BlockIds table input parameter containing the following:

Block scope
Block code

The custom view should then do the following:

Perform one or more operations using the block.
Use Lusid.Block.Writer to update any block values.
Output a success or error message using the WriteErrorCode.

To make the custom view available in the Order Blotter, you must register the OrderBlotterBlockAction metadata key with the view.

Example: Creating a block job that sets a contingent order ID

Let’s imagine you want to generate some order numbers for each block, ready for placement. You can use Sys.Admin.SetupView to define the following block job that can be run on any set of blocks, specifying in your query:

A name for the custom view
Optionally, a description
The required input parameters for a block job, as detailed above
The operation to perform on the block. In this example, the view uses Lusid.Sequence.Writer to generate an order number.
The values to write to the block using Lusid.Block.Writer
A success and an error message depending on the WriteErrorCode. For LUSID providers, a WriteErrorCode of 0 indicates the write operation was successful.

Outside of the custom view, you must use the Sys.Registration.Metadata.Writer provider to set the OrderBlotterBlockAction metadata value to true.

@@providerName = select 'set_contingent_order_id';

@table_blocks = select 'Finbourne-Examples' as scope, 'BLK-0' as code;

-- Create the custom view

@x = use Sys.Admin.SetupView with @@providerName, @table_blocks
--provider={@@providerName}
--description="A process that can be triggered for some blocks"
--parameters
BlockIds,Table,@table_blocks,false,"Pass in a table of data of block scopes and codes"
----

@block_ids = select * from #PARAMETERVALUE(BlockIds);

-- Trigger sequence and get contingent ID

@sequence = SELECT 1 as NextBatch,
'OrderBlock' as Code,
'Next' as WriteAction,
'Finbourne-Examples' as Scope;
@contingent_id = select NextValueInSequence as Contingent_Id, WriteErrorCode, WriteError from Lusid.Sequence.Writer where toWrite = @sequence;

@@contingent_id_string = SELECT Contingent_Id from @contingent_id LIMIT 1;

-- Add contingent IDs to the blocks
@blocks = SELECT
@@contingent_id_string as Contingent_Id,
b.* 
FROM @block_ids bi
INNER JOIN Lusid.Block b
ON bi.scope = b.BlockScope AND
bi.code = b.BlockCode;
        
-- Write updated values to the block
@insert = select * from Lusid.Block.Writer where toWrite = @blocks;

@@result = SELECT
CASE
    WHEN WriteErrorCode = 0 THEN 'Contingent IDs written as ' || Contingent_Id
    ELSE 'There was an issue with your Contingent ID. Error: ' || WriteError
END AS result
FROM @contingent_id LIMIT 1;

select @@result as result;

enduse;

@create_view = select * from @x;

--- Register metadata for the custom view

@metadata = values
  (@@providerName, 'OrderBlotterBlockAction', 'True');
@toWrite = select
  column1 as ProviderName,
  column2 as MetadataKey,
  column3 as MetadataValue
from @metadata;

select * from Sys.Registration.Metadata.Writer
  where ToWrite = @toWrite

Note: For the example above, you must first create a sequence with the specified scope and code using the CreateSequence API.

Once you have created a block job in the form of a custom view, to run it:

Navigate to Dashboard > Order Blotter in the LUSID web app.
Create your order blocks as usual.
Select the blocks you want to include in your block job.
Select a Block job from the dropdown.
Run the block job.

Once the block job has run, the dashboard displays your success or error message: