JSON Web Service - Introduction Core SDK Training: JSON Web Service - Introduction Welcome to CORE SDK Training. This lesson will introduce one of the key components of the Platform for Science (or PFS) Software Development Kit- the JSON Web Service. You can use the web service to build your own custom applications to enter or pull data out of your PFS system using your own user interface. Other components of the SDK are discussed in separate chapters.

Course Topics Understanding the JSON Web Service Understanding Entity References Navigating to the REST Tool Loading Request Templates Submitting Requests This lesson will explain how the PFS JSON Web Service generally works. It will cover the ways that you can refer to entities in the database. You will also learn how to access and use a REST Tool within the system to model your request and response calls. The REST tool will load JSON code templates that can be incorporated into your own code. You will also earn how to submit requests to the database directly through the REST Tool and view the database responses. CONFIDENTIAL

PFS JSON Web Service Only supported way to push data into PFS database outside of the standard user interface Contains a utility (REST Tool) to guide developers how to interface their applications with Core LIMS database by interactively building code templates The code templates are request and response calls written in JSON (JavaScript Object Notation) Since JSON is a text format that is language independent, these code templates can then be incorporated into most developer applications The code templates are stateless and there are no dependencies between multiple templates So what is the Platform for Science JSON Web Service? First, we should understand when you need to use the web service. If you cannot configure the standard user interface to meet your requirements or you want to build your own applications with additional functionality, the only way that you can push data into the PFS database outside of the regular user interface is through this web service. The web service can also be a convenient way to write data from instruments, other databases, or from your own automated scripts. You may also use the web service to pull data out for reports, but there are other reporting options outside of the SDK.   To assist you with creating code that calls this web service, there is a utility (called a REST tool) that guides developers in interfacing their applications with the CORE LIMS database by interactively building code templates. These code templates model database input and output calls to the database. The templates are written in JSON (short for JavaScript Object Notation), which can easily be incorporated into most applications because JSON is language independent. These code templates are stateless, so you do not need to worry about dependencies between multiple templates. CONFIDENTIAL

JSON Basics JSON is a lightweight text-data interchange format It uses similar syntax to JavaScript (but is language independent) Data is in name/value pairs Name and value are separated by a colon Strings are contained in quotes Data is separated by commas Curly brackets hold objects Square brackets hold arrays Name/values may be nested For more info see www.json.org Since the web service is based on code templates that are written in JSON, let's take a closer look at what JSON is. JSON is a lightweight text-data interchange format used to transmit objects consisting of attribute-value pairs. It's easy for humans to read and write and it's easy for machines to parse and generate. It uses similar syntax to JavaScript, but is language independent.   JSON is built on two universal data structures: First, it contains an unordered collection of name/value pairs often referred to as objects or records. Second, it contains an ordered list of values typically referred to as an array or list. To manage these structures, JSON uses a syntax that is similar to JavaScript. We just mentioned that an object is an unordered set of name/value pairs. JSON identifies objects by beginning with a left curly bracket and ending with a right curly bracket. { object } The object contains a set of data represented by name/value pairs where each name is followed by a colon then its value. A comma separates one name/value pair from the next. String values are contained within quotes. An array, very simply, is a collection of values. An array begins with a "[" left bracket and ends with a "]" right bracket. Arrays contain values separated by a comma ",". These values can be strings, represented in double quotes, numbers, True-False-or Null values, objects or another array. Any and all of these can be nested. For additional information on JSON and its structure, refer to www.json.org CONFIDENTIAL

Code Building Blocks Here is an example of the JSON syntax. JSON can be read like a sentence where the LIMS Entity types are like nouns and the SDK commands are similar to actions or verbs. The sentence may also contain additional parameters that are needed to fully define the action. There is no strict order or format that the sentence parts are required to be in.   Shown here is a sample HTTP browser request to the server. The request is taking information from the Browser and passing it to the server. The SDK Command "get" is the action that is being performed on Entity type or type parameter of "Car". The entity reference parameter allows the user to enter an ID for the desired record to retrieve information. The user can enter either the Car's name, entityid or barcode. These will all be returned by the template, within the response, along with any error messages that might apply. The code template that was provided by the web service is marked in red. The sentence can be spaced out as shown here, to make it easier to read. CONFIDENTIAL

Currently Available Actions Update an attribute of a sample/lot or general entity type Create a sample/lot or general entity type and set its values/associations Batch create sample/lots or general entity types Query by entity type criteria Get sample/lot or general entity type information and its values/associations Create a container Populate single well or multiple well containers Transfer from source to destination cells Add samples to an experiment Add data to an experiment Publish/unpublish experiments Execute triggers Get members of a queue Add or update queue members Get experiment data values Query by assay criteria Upload a file and attach it to an entity Most, but not all, of the common operations that you can perform in the standard user interface can be accessed through the JSON web service. Here is a list of actions that are currently supported within the web service.   Update an attribute of a sample/lot or general entity type Create a sample/lot or general entity type and set its values/associations Batch create sample/lots or general entity types Query by entity type criteria Get sample/lot or general entity type information and its values/associations Create a container Populate single well or multiple well containers Transfer from source to destination cells Add samples to an experiment Add data to an experiment Publish/unpublish experiments Execute triggers Get members of a queue Add or update queue members Get experiment data values Query by assay criteria Upload a file and attach it to an entity CONFIDENTIAL

Entity References Typically you can fill in either an entity name OR an entity ID OR an entity barcode into a request The entity name, ID, and barcode are all unique identifiers The entity name and barcode are displayed frequently throughout the GUI The entity ID is displayed in the URL only and not generally visible to end users, but is a more efficient lookup key Since it is more efficient, most responses will return the entity ID Most of the code templates provided by the JSON web service, allow users to specify either a unique name, a barcode or an entity ID. All three of these references are unique, so appropriate values for any of these parameters can be used for a request.   While the name and the barcode are readily displayed on all details pages for an entity, the Entity ID is not. The Entity ID is a 7+ digit numerical database key and is often a more efficient way to perform database searches and lookups. Because it is more efficient, many SDK responses may return the entity ID instead of a name or barcode and it may be better to use in requests if you know the value, perhaps from a previous request. For reference, you can sometimes see the ID displayed in the URL when a page is called. As it is more efficient to use the entity ID, most responses will return the entity ID. CONFIDENTIAL

Navigating to the SDK application From the main home page, click on the SDK tile OR from any page, select SDK from the application menu Now that we are familiar with what the JSON web service is, let’s take a closer look at how the REST tool works so that you can see how to access the code templates. The REST tool can be found within the PFS user interface. There is usually a menu that points to it within a SDK Application. This makes it convenient for you to limit access to only the developers that need this tool by just giving developers access to the SDK application. To begin, click on the Application Drop Down menu in the upper left corner of the page to expand it, and click on the SDK Application link. This will bring you to the SDK Application home page.   CONFIDENTIAL

Navigating to the REST Tool The SDK Tool is a web service design model based on REST (REpresentational State Transfer) principles It is simpler to use than SOAP or WSDL web services Within the SDK Application, select REST Tools from the SDK Menu > Rest Menu The SDK application basically consists of a single menu that points to the REST Tool that you can use to get code templates. Before we navigate to the page, let’s discuss what a REST Tool is. This utility is a web service design model that is based on REpresentational State Transfer Principles or REST for short. REST is much simpler to use than SOAP or WSDL web services.   Once you are on the SDK home page, you can access the utility by expanding the SDK menu option and then locating and clicking on the REST Tools link. CONFIDENTIAL

The REST Tool Developers will enter basic information about the objects they want to model The tool will build a JSON template in the request box Developers can modify the template to make more specific requests The tool will return the LIMS response in the Response box Developers can copy the JSON code for successful responses into their own applications This will bring you to the REST Tool page. Notice that this page does not have the same CORE LIMS title bar that the main user interface does. It looks a bit different.   This page will allow developers the ability to enter basic information about the objects they want to model. The tool will build a JSON template in the Request box that is located in the center of the page. Developers can then modify the template, at any time, to make more specific requests. The tool will return the LIMS response in the box labeled: Response. Developers can then copy the JSON code for the successful responses into their own applications. CONFIDENTIAL

Log In Enter you User Name and Password (the same as what you use to log into the LIMS) and select the Login button If you are a PFS customer, you will need to enter the Account Name The Tool will return Messages and tell you if the action was a success or not Tip: check here for messages also after submitting any request At the top of the page there will be a section allowing you to login to the utility. Re-enter the same username and password that you used when you logged into CORE LIMS. If you are on a shared multi-tenant system with access to more than one account, you will also need to enter the account name. You can find the account name displayed when you open up your Help Menu on any of the standard system pages. Next, select the Login button. The tool will return a message to tell you if the login was successful or not. Locate the Success: box to see the result. You can check here for messages that will display after submitting any request to the tool. Notice that the Messages box is giving you a database response that you can use to build your application. You will need the JSession ID information to access the webservice. CONFIDENTIAL

Loading a Request Template To start building a code template, select the SuperType and EntityType from the LIMS that you want to retrieve/create/or update Select the sdkCmd you want to use If you are using an update command, enter the LIMS barcode ID for the record you want to update Click on the Load JSON Template button to see the code returned in the Request box Let’s continue on to learn how to load a Request template. In the middle section, you will need to enter some basic parameters to define which request template you want to load. To start building a request template, first select the SuperType that you will be working with. You can simply select the supertype from the Supertype drop down list available. This list will generally be the same as the super types listed in the main admin panel, except for two additional items. There will be a hard coded option for "CELL" whish is used for some container requests and a hard coded asterisk option "*" which can be used to invoke a trigger. For a simple example, let’s select the Supplier super type.   Next, select the Entity Type within that SuperType from the Entity Type drop down list. This list also mirrors the list of entity types within the Main Admin panel and will be populated as soon as the super type has been selected. Let’s select the supplier entity type for this example. Now, select the sdkCommand that you want to use. Select from the drop down list of available options. This list will vary depending upon what super type you have selected. We will go into more details on specific commands in the next lesson. For this example, let’s use a simple Get command to look up a supplier record. If you are using an update command that requires you to look up the current data for you to modify, you will need to enter the LIMS barcode ID for the record you want to update. For any other command, the tool will ignore any value in the Barcode box so you can leave it blank. Finally, click on the Load JSON Template button. The code for the template will be displayed in the Request text box. If any errors occurred, check the Message box in the login section that we looked at earlier in this lesson. If needed, you can drag the bottom right corner of the Request template text box with your mouse to resize it if necessary. This may be needed if the entire response is not fully visible in the text box that is showing. There is also a Clear button to erase any templates that may have been previously loaded into the Request box. Be aware, however, that it will NOT clear any values in the Response text box next to it. There is no limit to the number of times you can load different requests into the page. If you load a new template request, it will automatically clear anything that was previously entered in the Request text box, before it displays the new template information. CONFIDENTIAL

Submitting a Request Modify the request to enter specific data such as LIMS barcode IDs or additional values for attributes Tip: Setting no filters will list all records Select the Submit button to execute the request Note: This will actually execute creates and updates in the database so be sure you are using a test system! The LIMS Response will be updated in the Response box Don’t forget to enlarge the text box or use scroll bars on the right to see ALL the data Use the Clear buttons to remove old data from the text boxes If you want to see how the database reacts when you enter values into the code template you can type values manually into the Request Template on the left. For example, if we want to look up a supplier with the barcode SU1 we can enter it directly in the template. Now click on the Submit button and view the response in the box on the right. Unless there are error messages, you will see all of the data for the requested supplier record displayed.   When you are working with the SDK, be sure to always work with a TEST system. Any inserts or updates that you make are actually being written directly to the database!!! CONFIDENTIAL

Verify the Record in the LIMS If you want to see how a record looks in the LIMS, you can use the Quick Find tool to find the record Enter the LIMS barcode in the text box and hit the magnifying glass button to jump to that record If you want to see what the record looks like in the LIMS, to verify your submission, you can use the Quick Find Tool to locate the record. Simply enter the barcode into the box and click on the magnifying glass to locate the record. For example, we can jump to our supplier record in the user interface and compare it to the values that are being passed from the REST tool.   CONFIDENTIAL

Review Understanding the JSON Web Service Understanding Entity References Navigating to the REST Tool Loading Request Templates Submitting Requests This chapter has introduced the JSON Web Service - what it is, how it works within CORE LIMS and how you can use it to build your own applications that can push or pull data from the LIMS. If there is any information you would like to review, please go back through this lesson at this time. If you are ready to move on, the next lesson will explore specific SDK commands.   Thank you for investing your time in CORE SDK Training. CONFIDENTIAL