Generating unique IDs for entities upserted into LUSID

Some LUSID entities require you to specify a unique ID when performing an upsert operation. For example, consider the transactionId field in the following call to the UpsertTransactions API:

curl -X POST 'https://<your-domain>.lusid.com/api/api/transactionportfolios/Equities/Growth/transactions'
   -H 'Authorization: Bearer <your-API-access-token>'
   -H 'Content-Type: application/json-patch+json'
   -d '[
      {
        "transactionId": "txn-equity-1",
        "type": "Buy",
        "instrumentIdentifiers": {"instrument/default/LusidInstrumentId": "LUID_00003D5C"},
        "transactionDate": "2021-11-15T00:00:00.0000000+00:00",
        "settlementDate": "2021-11-16T00:00:00.0000000+00:00",
        "units": 10,
        "transactionPrice": {"price": 350, "type": "Price" },
        "totalConsideration": {"amount": 3500, "currency": "GBP" },
        "transactionCurrency": "GBP"
     },
  ]'

You can use the APIs in the Sequences collection to help automate the process of creating unique values for use in an upsert (or any other) operation.

Creating a sequence

The first step is to create a sequence defining a number of values, and certain characteristics of those values.

Note: A sequence is single use unless you set its cycle field to true. By default, once you have exhausted the values in a sequence, you cannot obtain them again; this helps ensure values are unique. Only change cycle to true if you want to generate non-unique values.

1. Obtain an API token.

2. Call the CreateSequence API for a particular scope in your LUSID domain, specifying a code for the sequence and other characteristics in the body of the request. For example, the following call creates a test/oddNumber sequence consisting of 10 values, each with a prefix and a number between 1 and 19, in increments of 2 (so txn-equity-1, txn-equity-3, txn-equity-5 and so on):

   curl -X POST "https://<your-domain>.lusid.com/api/api/sequences/test"
     -H "Content-Type: application/json-patch+json"
     -H "Authorization: Bearer <your-api-access-token>"
     -d "{
          'code':'oddNumber',
          'increment':2,
          'minValue':1,
          'maxValue':19,
          'start':1,
          'cycle':false,
          'pattern':'txn-equity-{{seqValue}}'
     }"

   Note the response confirms the operation has succeeded but does not itself return the values:

   {
     "id": {
       "scope": "test",
       "code": "oddNumber"
     },
     "increment": 2,
     "minValue": 1,
     "maxValue": 19,
     "start": 1,
     "cycle": false,
     "pattern": "txn-equity-{{seqValue}}",
      ...
   }

Obtaining the values in a sequence

You can obtain the values in a sequence either one at a time or in batches.

To do this, call the Next API for the scope and code of the sequence as many times as you need. For example, the first call to Next for the test/oddNumber sequence :

curl -X GET "https://<your-domain>.lusid.com/api/api/sequences/test/oddNumber/next?batch=2"
  -H "Authorization: Bearer <your-api-access-token>"

...retrieves the first two values (to retrieve singly, omit the batch parameter):

{
  "values": [
    "txn-equity-1",
    "txn-equity-3"
  ],
   ...
}

The second call to Next retrieves the next two values, and so on:

{
  "values": [
    "txn-equity-5",
    "txn-equity-7"
  ],
   ...
}