Introduction and Requirements

This topic is aimed at developers implementing the interface between Espresso ELN and a third party product batch registration system. ELN users can skip this section. 

The product batch registration interface of Espresso ELN consists of a single server script to be adapted to a third party registration system. The ELN calls the individual script functions based on user actions, supplying all required data for performing the requested task. The developer-inserted third party registration system API calls (see yellow code sections below) then consume the provided data and return a result, which finally is transferred back to the ELN. The insertion of as little as three lines of code is required for this. A fully documented sample PHP script can be downloaded here. 

To be able to utilize this interface, your registration system must expose a public API containing following basic functionalities, which can be called by a server script: 

  • Create Batch: A new batch is registered. The auto-generated batch-ID must be returned immediately by the function (the ELN is waiting for the response). Sending the request to a staging area for later human processing is not supported.
  • Update Batch: The properties of an existing batch are updated. Immediate return of success/failure status is preferred.
  • Delete Batch: An existing batch is deleted. Immediate return of success/failure status is preferred.

Business logic and validation are performed by the third party system, which is considered as a black box returning the resulting batch-ID and/or the status of the other operations. If the third party API should not be fully documented, or if you are uncertain about its implementation, you might need to consult its vendor.

Interface Script Path

Place the interface script on a server with straightforward access to your batch registration system, as well as to all ELN users. The server must have at least PHP 7 installed if utilizing a PHP script. The ELN obtains the path to the script either via the corresponding global ELN Admin Tool policy setting ('Product Batch Registration') or via the local application settings ('Batch Registration script URL'). For testing, it is highly recommended to disconnect the test clients from the server and to utilize their local settings for specifying the script path, instead of a global assignment via ELN Admin Tool. This ensures that the batch registration interface elements don't become visible to all ELN users while testing.

Registration System Info

The ELN requires some basic information about the third party registration system for providing appropriate responses. In the code sections below, the areas highlighted in yellow mark the parts where modifications by system-specific code are required. The other parts of the script should remain unchanged for granting the expected behavior:

function GetRegistrationInfo(){


  // Modify according to your registration system

  $isStructureBased = true;  // Set to true if the generated batch-ID's are structure-based

  $useSDFileOnly = false;    // Set to true if your registration system API can process SDFiles only

  // ------------------

  • $isStructureBased: Set this variable to true, if the generated batch-IDs are structure-based, i.e. of the form prefix-structureNumber-batchNumber. Most systems will generate IDs of this form, where ID's of the same structure only differ by their incremental batch number. If true, the modification of the structure of an already registered batch will cause a user warning allowing to cancel to operation. If continued anyway, a the registration system is requested to delete the batch, since batch-ID and structure become mismatched. - If the variable is set false, the batch ID is independent from the structure and the batch will be silently updated after structure modification.
  • $useSDFileOnly: The ELN passes all available product property information to the script (see next topic). Set this variable to true, if your registration systems only can handle SDFiles as data input. Otherwise set it to false, which provides more flexibility for handling the individual parameters. 

Register/Update a Batch

When requesting a batch registration or update, the ELN passes all available product properties to the interface script in JSON format. All properties not annotated as '(can be unspecified)' are guaranteed to contain values. Here's how the passed properties can be retrieved from the deserialized JSON payload (PHP):

 $updateBatchID = $prodInfo -> UpdateBatchID;  // batch-ID if updating, empty string if creating batch

 $molfile = $prodInfo -> Molfile;              // product molfile

 $experimentID = $prodInfo -> ExperimentID;    // the unique ID of the experiment producing the batch 

 $molweight = $prodInfo -> MW;                 // product molecular weight

 $inchiKey=$prodInfo -> InChIKey;              // the InChIKey of the product

 $elemental = $prodInfo -> EF;                 // elemental formula of the product

 $author = $prodInfo -> Author;                // unique ID of the person producing the batch

 $purity = $prodInfo -> Purity;                // batch purity in percent

 $grams = $prodInfo -> Grams;                  // the batch amount, scaled to grams

 $amount = $prodInfo -> Amount;                // user specified batch amount

 $unit = $prodInfo ->  Unit;                   // user specified batch unit ('mg', 'g', or 'kg')

 $projName = $prodInfo -> ProjectName;         // project name

 $physForm =  $prodInfo -> PhysicalForm;       // will be 'liquid', 'solid', 'crystals', 'oil', 'gum', 'foam' or

                                               //'unspecified'

 $ee = $prodInfo -> EE;                        // enantimeric excess (can be unspecified)

 $de = $prodInfo -> DE;                        // diastereomeric excess (can be unspecified)

 $mp_upper = $prodInfo -> MP_Upper;            // upper limit of the melting point range (can be unspecified)

 $mp_lower = $prodInfo -> MP_Lower;            // lower limit of the melting point range (can be unspecified)

 $bp_upper =  $prodInfo -> BP_Upper;           // upper limit of the boiling point range (can be unspecified)

 $bp_lower =  $prodInfo -> BP_Lower;           // lower limit of the boiling point range (can be unspecified)

 $bp_pressure =  $prodInfo -> BP_Pressure;     // boiling point pressure in mbar (can be unspecified)

 $color =  $prodInfo -> Color;                 // color of the batch (can be unspecified)

 $resinLoad =  $prodInfo -> ResinLoad;         // resin load in percent, if attached to a resin (can be unspecified)

If $useSDFileOnly (see above) is set to false, then the individual product properties as listed above are available. - If set to true, however, above variables contain no values. Instead, the script variable $SDFileStr contains all properties as a single string in SDFile format. This variable contains no value if $useSDFileOnly is set to false.

 $SDFileStr = $prodInfo -> SDFile;

Implement Batch Create/Update

Some or all of above product properties may serve as input parameters for the actual Create or Update API calls of your batch registration system. Please consult its vendor in case of any uncertainties about their implementation. Replace the lines ' // ....' in the script by the individual API call(s). When done, it is also important to assign the correct response codes to provide feedback to the ELN about the outcome, which in turn will inform the user accordingly. Please note that the creation of a new batch entry is required to be immediate, since the ELN waits for the returned batch-ID. For batch updates, delayed processing e.g. due to transfer into a staging area, is acceptable (response code 202).  

  if($isUpdating == false){


    // Your API call(s) for CREATING a new product batch based on above product data

    // ........


    $batchID = 'myBatchID';    // replace this by the actually created batch ID

    http_response_code(201);   // 201: The batch was successfully created (action must be immediate)

                               // 400: An error was returned by the registration API, the action failed.  

  } else {


    // Your API call(s) for UPDATING the product batch specified by $updateBatchID based on above product data 

    // .........


    $batchID = $updateBatchID;  

    http_response_code(201);   // 201: The batch was immediately updated.

                               // 202: An update request was placed to a staging area for later processing. 

                               // 400: An error was returned by the registration API, the action failed.  

  }

Please note that $updateBatchID contains an empty string when creating a new batch. When updating, it contains the ID of the batch to be updated.

Delete a Batch

When the ELN requests a batch delete operation, it passes the batch-ID of the entry to be deleted, the cancel reason and other other relevant information:

$batchID = $cancelInfo -> BatchID;            // ID of the batch to be deleted 

$cancelReason = $cancelInfo -> CancelReason;  // reason for deletion ('user_revoked', 'product_deleted'

                                              // 'structure_deleted' or 'structure_modified') 

$author = $cancelInfo -> Author;              // requesting user (full name)   

$userID = $cancelInfo -> UserID;              // userID of the requesting user

$experimentID = $cancelInfo -> ExperimentID;  // experimentID the product batch belongs to

       

// Add here your API call(s) for deleting a product batch.

// ....................


http_response_code(201);   // 201: The batch was deleted immediately.

                           // 202: A delete request was placed to a staging area and will be processed later.

                           // 400: An error was returned by the registration API, the action failed. 

The fully documented sample PHP script can be downloaded here.