57

XML-RPC web services provider
The j5 XML-RPC web service (located at https://j5.jbei.org/bin/j5_xml_rpc.pl) provides additional access to running j5. XML-RPC is a XML-encoded Remote Procedure Calling protocol over HTTP. For more information, visit the XML-RPC website for its specifications.

Note: see the very bottom of this page for example j5 XML-RPC service perl-script clients, as well as information concerning which perl modules need to be installed on the client machine to use the j5 XML-RPC service.

There are currently seven methods implemented for the j5 XML-RPC web service: CreateNewSessionId, GetLastUpdatedUserFiles, DesignAssembly, CondenseMultipleAssemblyFiles, DesignDownstreamAutomation, ConvertSBOLXML and ReturnErrorMessage. These methods are described below.

j5 XML-RPC client perl-script implementations are also provided at the bottom of this page for each of the six methods.

CreateNewSessionId

Access to j5 requires a valid j5 session ID. When you log in to j5 using its simplified web page interface, a j5 session ID is automatically created for you (behind the scenes) and the session ID is stored as a cookie in your browser. When accessing j5 via a web browser, j5 checks if you have a valid j5 session ID cookie before allowing you to design any assemblies.

The j5 XML-RPC web service requires the same user-authentication as its simplified web page interface does. Thus, it is important to acquire a valid j5 session ID before using the service. CreateNewSessionId is a method that serves this purpose.

In perl (using the XML::RPC module), the syntax for calling this method looks like:
$xmlrpc->call( 'CreateNewSessionId', { username => $username, password => $password } );

Essentially, the parameters are passed in as an object that contains key => value pairs.

In XML, an example call to the j5 XML-RPC web service would look like:
<?xml version="1.0" encoding="UTF-8" ?>
   <methodCall>
      <methodName>CreateNewSessionId</methodName>
      <params>
         <param>
            <value>
               <struct>
                  <member>
                     <name>password</name>
                     <value>
                        <string><![CDATA[my_password]]></string>
                     </value>
                  </member>
                  <member>
                     <name>username</name>
                     <value>
                        <string><![CDATA[my_username]]></string>
                     </value>
                  </member>
               </struct>
            </value>
         </param>
      </params>
   </methodCall>

Here is the actual xml file:
CreateNewSessionId_query.xml:

Note that the username and password are the same as you would use for access to the simplified web page interface for j5. Accounts are available at the j5 website's request an account page.

In response, the j5 XML-RPC server returns an object that also contains key => value pairs. In perl, this looks like:
return { j5_session_id => $j5_session_id, };

In XML, an example response from the j5 XML-RPC web service would look like:
<?xml version="1.0" encoding="UTF-8" ?>
   <methodResponse>
      <params>
         <param>
            <value>
               <struct>
                  <member>
                     <name>j5_session_id</name>
                     <value>
                        <string><![CDATA[my_session_id]]></string>
                     </value>
                  </member>
               </struct>
            </value>
         </param>
      </params>
   </methodResponse>

Here is the actual xml file:
CreateNewSessionId_response.xml:

You can then (repetitively) use this newly created j5 session ID (up until its expiration date of 10 hours post creation) when calling any of the three other j5 XML-RPC methods below.

See the bottom of this page for an example perl script that calls the j5 XML-RPC service to perform the CreateNewSessionId method.

GetLastUpdatedUserFiles

As described in the overview of the j5 simplified web-page interface, there are nine input files required for designing a DNA assembly with j5: 1) the j5 parameters file, 2) the sequences list file, 3) the zipped sequences file, 4) the parts list file, 5) the target part order list file, 6) the Eugene rules list file, 7) the master plasmids list file, 8) the master oligos list file, and 9) the master direct syntheses list file. The j5 server keeps the last-updated versions of these files for you, so that you may re-use them without having to re-upload them. The GetLastUpdatedUserFiles method provides user access to these files (if they exist of course).

In perl, calling this method looks like:
$xmlrpc->call( 'GetLastUpdatedUserFiles', { j5_session_id => $j5_session_id } );

In XML, this would look very similar in form to the example shown above for the CreateNewSessionId method.

Here is the actual xml file:
GetLastUpdateUserFiles_query.xml:

In response, the server returns an object that, in perl, looks like:
return {
      username => $username,
      j5_parameters_file_exists => $j5_parameters_file_exists,
      encoded_j5_parameters_file => $encoded_j5_parameters_file,
      downstream_automation_parameters_file_exists => $downstream_automation_parameters_file_exists,
      encoded_downstream_automation_parameters_file => $encoded_downstream_automation_parameters_file,
      sequences_list_file_exists => $sequences_list_file_exists,
      encoded_sequences_list_file => $encoded_sequences_list_file,
      zipped_sequences_file_exists => $zipped_sequences_file_exists,
      encoded_zipped_sequences_file => $encoded_zipped_sequences_file,
      parts_list_file_exists => $parts_list_file_exists,
      encoded_parts_list_file => $encoded_parts_list_file,
      target_part_order_list_file_exists => $target_part_order_list_file_exists,
      encoded_target_part_order_list_file => $encoded_target_part_order_list_file,
      eugene_rules_list_file_exists => $eugene_rules_list_file_exists,
      encoded_eugene_rules_list_file => $encoded_eugene_rules_list_file,
      master_plasmids_file_exists => $master_plasmids_file_exists,
      encoded_master_plasmids_file => $encoded_master_plasmids_file,
      master_oligos_file_exists => $master_oligos_file_exists,
      encoded_master_oligos_file => $encoded_master_oligos_file,
      master_direct_syntheses_file_exists => $master_direct_syntheses_file_exists,
      encoded_master_direct_syntheses_file => $encoded_master_direct_syntheses_file,
     };

In XML, this would look very similar in structure to the example shown above for the CreateNewSessionId method.

Here is the actual xml file:
GetLastUpdateUserFiles_response.xml:

The username is the username associated with the j5_session_id used when calling the method.

The ...file_exists values are either "TRUE" or "FALSE".

The encoded_..._file values are the string representations of their associated base64-encoded files. If the corresponding ...file_exists value is "FALSE", these values are not defined.

See the bottom of this page for an example perl script that calls the j5 XML-RPC service to perform the GetLastUpdateUserFiles method.

DesignAssembly

As described in the overview of the j5 simplified web-page interface, there are six different assembly method options: SLIC/Gibson/CPEC, Combinatorial SLIC/Gibson/CPEC, Mock Assembly, Golden Gate, Combinatorial Golden Gate, and Combinatorial Mock Assembly. This method provides user access to designing all four assembly methods.

In perl, for the non-Mock assembly methods, calling this method looks like:
$xmlrpc->call( 'DesignAssembly', {
                 j5_session_id => $j5_session_id,
                 reuse_j5_parameters_file => $reuse_j5_parameters_file,
                 encoded_j5_parameters_file => $encoded_j5_parameters_file,
                 reuse_sequences_list_file => $reuse_sequences_list_file,
                 encoded_sequences_list_file => $encoded_sequences_list_file,
                 reuse_zipped_sequences_file => $reuse_zipped_sequences_file,
                 encoded_zipped_sequences_file => $encoded_zipped_sequences_file,
                 reuse_parts_list_file => $reuse_parts_list_file,
                 encoded_parts_list_file => $encoded_parts_list_file,
                 reuse_target_part_order_list_file => $reuse_target_part_order_list_file,
                 encoded_target_part_order_list_file => $encoded_target_part_order_list_file,
                 reuse_eugene_rules_list_file => $reuse_eugene_rules_list_file,
                 encoded_eugene_rules_list_file => $encoded_eugene_rules_list_file,
                 reuse_master_plasmids_file => $reuse_master_plasmids_file,
                 encoded_master_plasmids_file => $encoded_master_plasmids_file,
                 master_plasmids_list_filename => $master_plasmids_list_filename,
                 reuse_master_oligos_file => $reuse_master_oligos_file,
                 encoded_master_oligos_file => $encoded_master_oligos_file,
                 master_oligos_list_filename => $master_oligos_list_filename,
                 reuse_master_direct_syntheses_file => $reuse_master_direct_syntheses_file,
                 encoded_master_direct_syntheses_file => $encoded_master_direct_syntheses_file,
                 master_direct_syntheses_list_filename => $master_direct_syntheses_list_filename,
                 assembly_method => $assembly_method,                }
         );

In perl, for the Mock assembly methods, calling this method looks like:
$xmlrpc->call( 'DesignAssembly', {
                 j5_session_id => $j5_session_id,
                 reuse_j5_parameters_file => $reuse_j5_parameters_file,
                 encoded_j5_parameters_file => $encoded_j5_parameters_file,
                 reuse_sequences_list_file => $reuse_sequences_list_file,
                 encoded_sequences_list_file => $encoded_sequences_list_file,
                 reuse_zipped_sequences_file => $reuse_zipped_sequences_file,
                 encoded_zipped_sequences_file => $encoded_zipped_sequences_file,
                 reuse_parts_list_file => $reuse_parts_list_file,
                 encoded_parts_list_file => $encoded_parts_list_file,
                 reuse_target_part_order_list_file => $reuse_target_part_order_list_file,
                 encoded_target_part_order_list_file => $encoded_target_part_order_list_file,
                 reuse_eugene_rules_list_file => $reuse_eugene_rules_list_file,
                 encoded_eugene_rules_list_file => $encoded_eugene_rules_list_file,
                 reuse_master_plasmids_file => $reuse_master_plasmids_file,
                 encoded_master_plasmids_file => $encoded_master_plasmids_file,
                 master_plasmids_list_filename => $master_plasmids_list_filename,
                 assembly_method => $assembly_method,                }
         );

In XML, this would look very similar in form to the example shown above for the CreateNewSessionId method.

Here is the actual xml file:
DesignAssembly_query.xml:

The reuse_..._file values should either be "TRUE" or "FALSE", and determine if the j5 server will re-use the last-updated version of the associated files when designing the assembly. An error message will result if one of these values is set to "TRUE", and the associated file does not (yet) exist on the server. To check against this, use the GetLastUpdatedUserFiles method, described above.

The encoded_..._file values should be the string representations of the base64-encoded associated files. These values have no effect if the corresponding reuse_..._file value is set to "TRUE".

The master_..._filename values should be the string file names of their associated master plasmids, oligos, and direct syntheses files. As described in the master plasmids list input file documentation, these filenames may determine the initial naming of the plasmids, oligos, and direct syntheses fragments (if the files themselves are empty and do not contain anything).

The assembly_method value should either be "SLIC/Gibson/CPEC" or "CombinatorialSLICGibsonCPEC" or "GoldenGate" or "CombinatorialGoldenGate" or "Mock" or "CombinatorialMock", depending on the assembly method to be designed. These choices essentially replicate the options presented in the simplified web-page interface for j5.

In response, if there were no j5 errors while designing the assembly, the server returns an object that, in perl, looks like:
return { output_filename => $output_filename, encoded_output_file => $encoded_output_file, }

In XML, this would look very similar in structure to the example shown above for the CreateNewSessionId method.

Here is the actual xml file:
DesignAssembly_response.xml:

The outputfilename is the name of the file associated with the j5 output zip file. As noted in the j5 simplified web-page interface documentation, the name of the output zip file will be of the form "j5_username_yearmonthdayhourminutesecond.zip" (e.g. "j5_J5_20100723134640.zip" if the username was "J5" and the assembly was designed at 1:46PM (and 40 seconds) on July 23, 2010).

The encoded_output_file is the string representation of the base64-encoded j5 output zip file.

However, if there was a j5 error while designing the assembly, the server returns an object that, in perl, looks like:
return { error_message => $error_message, output_filename => $output_filename, encoded_output_file => $encoded_output_file, }

The error_message is the error message that j5 generated when it had a problem during the design process.

The outputfilename and the encoded_output_file are identical to that described above, except in the context of a j5 error, the base64-encoded j5 output zip file contains the working directory used by j5 when the error occurred. This working directory can be very useful when determining what caused the error (i.e., for debugging purposes).

See the bottom of this page for an example perl script that calls the j5 XML-RPC service to perform the DesignAssembly method.

CondenseMultipleAssemblyFiles

As described in the overview of the j5 simplified web-page interface, it is possible to use j5 to condense multiple assembly files into a single aggregated assembly file. This method provides user access to this j5 feature.

In perl, calling this method looks like:
$xmlrpc->call( 'CondenseMultipleAssemblyFiles', {
                j5_session_id => $j5_session_id,
                encoded_assembly_files_to_condense_file => $encoded_assembly_files_to_condense_file,
                encoded_zipped_assembly_files_file => $encoded_zipped_assembly_files_file,                }
    );

In XML, this would look very similar in form to the example shown above for the CreateNewSessionId method.

Here is the actual xml file:
CondenseMultipleAssemblyFiles_query.xml:

The encoded_..._file values should be the string representations of the base64-encoded associated files.

In response, if there were no j5 errors while condensing the assembly files, the server returns an object that, in perl, looks like:
return { output_filename => $output_filename, encoded_output_file => $encoded_output_file, }

In XML, this would look very similar in structure to the example shown above for the CreateNewSessionId method.

Here is the actual xml file:
CondenseMultipleAssemblyFiles_response.xml:

The outputfilename is the name of the file associated with the j5 output zip file. As noted in the j5 simplified web-page interface documentation, the name of the output zip file will be of the form "j5_username_yearmonthdayhourminutesecond.zip" (e.g. "j5_J5_20100723134640.zip" if the username was "J5" and the assembly was designed at 1:46PM (and 40 seconds) on July 23, 2010).

The encoded_output_file is the string representation of the base64-encoded j5 output zip file.

However, if there was a j5 error while condensing the assembly files, the server returns an object that, in perl, looks like:
return { error_message => $error_message, output_filename => $output_filename, encoded_output_file => $encoded_output_file, }

The error_message is the error message that j5 generated when it had a problem during the condensing process.

The outputfilename and the encoded_output_file are identical to that described above, except in the context of a j5 error, the base64-encoded j5 output zip file contains the working directory used by j5 when the error occurred. This working directory can be very useful when determining what caused the error (i.e., for debugging purposes).

See the bottom of this page for an example perl script that calls the j5 XML-RPC service to perform the CondenseMultipleAssemblyFiles method.

DesignDownstreamAutomation

As described in the overview of the j5 simplified web-page interface, it is possible to use j5 to automate downstream processes, such as distributing PCR reactions across a thermocycler block annealing temperature gradient. This method provides user access to these j5 features.

There are currently two downstream automation tasks that j5 can design: DistributePcrReactions, and DistributeSplitAndPoolPcrReactions. This method provides user access to designing these downstream processes.

In perl, calling this method looks like:
$xmlrpc->call( 'DesignDownstreamAutomation',
            {
            j5_session_id => $j5_session_id,
            reuse_downstream_automation_parameters_file => $reuse_downstream_automation_parameters_file,
            encoded_downstream_automation_parameters_file => $encoded_downstream_automation_parameters_file,
            encoded_plate_list_file => $encoded_plate_list_file,
            encoded_zipped_plate_files_file => $encoded_zipped_plate_files_file,
            encoded_assembly_to_automate_file => $encoded_assembly_to_automate_file,
            automation_task => $automation_task,
            }
    );

In XML, this would look very similar in form to the example shown above for the CreateNewSessionId method.

Here is the actual xml file:
DesignDownstreamAutomation_query.xml:

The reuse_..._file values should either be "TRUE" or "FALSE", and determine if the j5 server will re-use the last-updated version of the associated files when designing the assembly. An error message will result if one of these values is set to "TRUE", and the associated file does not (yet) exist on the server. To check against this, use the GetLastUpdatedUserFiles method, described above.

The encoded_..._file values should be the string representations of the base64-encoded associated files.

The automation_task value should be "DistributePcrReactions" (or eventually other tasks as they are implemented) depending on the downstream automation task to be designed. These choices essentially replicate the options presented in the simplified web-page interface for j5.

In response, if there were no j5 errors while designing the downstream automation, the server returns an object that, in perl, looks like:
return { output_filename => $output_filename, encoded_output_file => $encoded_output_file, }

In XML, this would look very similar in structure to the example shown above for the CreateNewSessionId method.

Here is the actual xml file:
DesignDownstreamAutomation_response.xml:

The outputfilename is the name of the file associated with the j5 output zip file. As noted in the j5 simplified web-page interface documentation, the name of the output zip file will be of the form "j5_username_yearmonthdayhourminutesecond.zip" (e.g. "j5_J5_20100723134640.zip" if the username was "J5" and the task was completed at 1:46PM (and 40 seconds) on July 23, 2010).

The encoded_output_file is the string representation of the base64-encoded j5 output zip file.

However, if there was a j5 error while designing the downstream automation, the server returns an object that, in perl, looks like:
return { error_message => $error_message, output_filename => $output_filename, encoded_output_file => $encoded_output_file, }

The error_message is the error message that j5 generated when it had a problem during the design process.

The outputfilename and the encoded_output_file are identical to that described above, except in the context of a j5 error, the base64-encoded j5 output zip file contains the working directory used by j5 when the error occurred. This working directory can be very useful when determining what caused the error (i.e., for debugging purposes).

See the bottom of this page for an example perl script that calls the j5 XML-RPC service to perform the DownstreamAutomation method.

ConvertSBOLXML

As described in the overview of the j5 SBOL XML <-> Genbank conversion tool simplified web-page interface, it is possible to use j5 to convert SBOL XML <-> GenBank format files. This method provides user access to this j5 feature.

In perl, calling this method looks like:
$xmlrpc->call( 'ConvertSBOLXML', {
                j5_session_id => $j5_session_id,
                encoded_to_be_converted_file => $encoded_to_be_converted_file,
                conversion_method => $conversion_method,                }
    );

In XML, this would look very similar in form to the example shown above for the CreateNewSessionId method.

Here is the actual xml file:
ConvertSBOLXML_query.xml:

The encoded_..._file values should be the string representations of the base64-encoded associated files.

The conversion_method value should either be "ConvertGenBankToSBOLXML" or "ConvertSBOLXMLToGenBankClean" or "ConvertSBOLXMLToGenBankPreserveSBOLInformation", depending on the conversion method to be applied. These choices essentially replicate the options presented in the simplified j5 SBOL XML <-> Genbank conversion tool web-page interface.

In response, if there were no j5 errors while converting the sequence file, the server returns an object that, in perl, looks like:
return { output_filename => $output_filename, encoded_output_file => $encoded_output_file, }

In XML, this would look very similar in structure to the example shown above for the CreateNewSessionId method.

Here is the actual xml file:
ConvertSBOLXML_response.xml:

The outputfilename is the name of the file associated with the j5 output zip file. As noted in the j5 SBOL XML <-> Genbank conversion tool simplified web-page interface documentation, the name of the output zip file will be of the form "j5_SBOLConverter_yearmonthdayhourminutesecond.zip" (e.g. "j5_SBOLConverter_20100723134640.zip" if the file was converted at 1:46PM (and 40 seconds) on July 23, 2010).

The encoded_output_file is the string representation of the base64-encoded j5 output zip file.

However, if there was a j5 error while converting the sequence file, the server returns an object that, in perl, looks like:
return { error_message => $error_message, output_filename => $output_filename, encoded_output_file => $encoded_output_file, }

The error_message is the error message that j5 generated when it had a problem during the conversion process.

The outputfilename and the encoded_output_file are identical to that described above, except in the context of a j5 error, the base64-encoded j5 output zip file contains the working directory used by j5 when the error occurred. This working directory can be very useful when determining what caused the error (i.e., for debugging purposes).

See the bottom of this page for an example perl script that calls the j5 XML-RPC service to perform the ConvertSBOLXML method.

ReturnErrorMessage

This method provides developer access to a generic error message for testing purposes.

In perl, calling this method looks like:
$xmlrpc->call( 'ReturnErrorMessage' );

Here is the actual xml file:
ReturnErrorMessage_query.xml:

In response, the server returns an generic test error message. Here is the actual xml file:
ReturnErrorMessage_response.xml:

See the bottom of this page for an example perl script that calls the j5 XML-RPC service to perform the ReturnErrorMessage method.

Example j5 XML-RPC service perl-script clients:

Note, since the j5 XML-RPC service is now running under SSL (via https://) it is necessary that you have the perl modules IO::Socket::SSL and Crypt::SSLeay installed on the client machine in order to have XML-RPC service perl-script clients presented below to work.

The following perl modules may be easily installed through the command line: perl -MCPAN -e 'install module_name'
The CPAN shell can also be initiated through the command line: perl -MCPAN -e shell

IO::Socket::SSL
A perl module available at:
http://search.cpan.org/~sullr/IO-Socket-SSL-2.006/lib/IO/Socket/SSL.pod

Crypt::SSLeay
A perl module available at:
http://search.cpan.org/dist/Crypt-SSLeay/SSLeay.pm

The following programs are free software; you can redistribute them and/or modify them under the same terms as the Perl "Artistic License". By downloading these programs, you are agreeing to the Perl "Artistic License" terms.

Copyright (c) 2010-2015, The Regents of the University of California, through Lawrence Berkeley National Laboratory (subject to receipt of any required approvals from the U.S. Dept. of Energy). All rights reserved.

NOTICE. This software was developed under funding from the U.S. Department of Energy. As such, the U.S. Government has been granted for itself and others acting on its behalf a paid-up, nonexclusive, irrevocable, worldwide license in the Software to reproduce, prepare derivative works, and perform publicly and display publicly. Beginning five (5) years after the date permission to assert copyright is obtained from the U.S. Department of Energy, and subject to any subsequent five (5) year renewals, the U.S. Government is granted for itself and others acting on its behalf a paid-up, nonexclusive, irrevocable, worldwide license in the Software to reproduce, prepare derivative works, distribute copies to the public, perform publicly and display publicly, and to permit others to do so.

Here is an example perl script that calls the j5 XML-RPC service to perform the CreateNewSessionId method:
j5_xml_rpc_client_create_new_j5_session_id.pl.zip:

Here is an example perl script that calls the j5 XML-RPC service to perform the GetLastUpdateUserFiles method:
j5_xml_rpc_client_get_last_updated_user_files.pl.zip:

Here is an example perl script that calls the j5 XML-RPC service to perform the DesignAssembly method:
j5_xml_rpc_client_design_assembly.pl.zip:

Here is an example perl script that calls the j5 XML-RPC service to perform the CondenseMultipleAssemblyFiles method:
j5_xml_rpc_client_condense_multiple_assembly_files.pl.zip:

Here is an example perl script that calls the j5 XML-RPC service to perform the DesignDownstreamAutomation method:
j5_xml_rpc_client_design_downstream_automation.pl.zip:

Here is an example perl script that calls the j5 XML-RPC service to perform the ConvertSBOLXML method:
j5_xml_rpc_client_convert_SBOLXML.pl.zip:

Here is an example perl script that calls the j5 XML-RPC service to perform the ReturnErrorMessage method:
j5_xml_rpc_client_return_error_message.pl.zip: