3 Developing an Adapter

Developing an adapter requires you to understand the overall process. You should plan your programs and packages carefully.

For details on this process, see the following:

• Adapter Development Process
  The adapter development process is detailed. You should understand this process before beginning your development.
• Planning Programs and Packages
  Each custom function and procedure required for your adapter must be contained in a PL/SQL package (Package B) and the package must be uploaded to a Source Code definition in the Program definition in your Adapter Area.
• Using the Security API Package During Development
  You must call a security API, CDR_PUB_API_INITIALIZATION, from every package that calls an Oracle Life Sciences Data Hub API and that you intend to run from outside Oracle Life Sciences Hub.

Adapter Development Process

The adapter development process is detailed. You should understand this process before beginning your development.

The following diagram depicts the process required to create an adapter.

Figure 3-1 Adapter Development Process

Description of "Figure 3-1 Adapter Development Process"

To develop an adapter, work in SQL Developer or a similar tool, using your own Oracle Life Sciences Data Hub user account that is linked to a database account with Execute privileges on the API security package CDR_PUB_API_INITIALIZATION.

1. Design your adapter, following instructions in this guide.
2. Create one or more service types and extend lookups as required; see Planning Services and Adding Lookup Values.
3. In your own schema, create two PL/SQL packages:
   • Package A: API Calls to Create metadata Objects. This package must call the APIs described in Using APIs to Create Required Metadata Objects. Package A must create an Adapter Domain, Adapter Area, technology type, and all the required Oracle Life Sciences Hub objects (metadata) including a Program, upload Package B as source code for the Program, assign a user group to the Adapter Area, and install the Adapter Work Area.

     Note:

     When you run the APIs to create a technology type and an Adapter Area, you must enter the names of all your custom functions and procedures as input parameter values, and set flags to indicate whether or not you are using any of the three possible Parameter Sets.

     Therefore you must determine which custom functions and procedures and Parameter Sets you need, and give the functions and procedures names, before you can complete Package A. See Designing an Adapter.

   • Package B: Custom Functions and Procedures. This package contains the functions and procedures that you write to do the work of the adapter; see Planning PL/SQL Functions and Procedures.
4. Run Package A. The system creates the required metadata objects, including the technology type, and uploads Package B as the source code for the adapter.
5. Follow the steps in Checking In Objects and Setting Their Validation Status, and Setting Up an Adapter to set up your adapter in your Oracle Life Sciences Hub instance.
6. In Oracle Life Sciences Hub, create an object definition and instance of the type relevant for your adapter: a Load Set, Data Mart, Program, or Business Area.

   You may need to create an Oracle Life Sciences Hub Domain, Application Area, and Work Area to contain the object (Load Set, Program, Data Mart, or Business Area) definition and instance; Table definitions and instances for the object to read from or write to; install the Work Area, and load data.

7. Test the adapter by checking that the required UI elements appear on screen and that it is possible to define, install and run the object.
8. You can debug and modify your functions and procedures in your own schema. Use APIs to check out the Program in the Adapter Area, upload the revised source code, and reinstall the Adapter Area's Work Area, and then test again. See the Oracle Life Sciences Data Hub Application Programming Interface Guide.
9. Modify Package B as required. Upload the modified package using the Modify Source Code public API.
10. Set the validation status of your objects to Quality Control and then to Production according to your standard operating procedures; see Checking In Objects and Setting Their Validation Status.

Planning Programs and Packages

Each custom function and procedure required for your adapter must be contained in a PL/SQL package (Package B) and the package must be uploaded to a Source Code definition in the Program definition in your Adapter Area.

The required functions and procedures can all be in the same package or in different packages. If multiple people are developing the adapter, it may be helpful for each of them to work on a separate package, upload each package to a different Source Code definition and create a different Program for each Source Code definition so that each Program can be installed separately. However, all Program instances must be contained in the same Work Area.

Note:

It is very important to have only one Work Area in an Adapter Area. This ensures that all the custom PL/SQL packages you write are installed in the same schema.

Using the Security API Package During Development

You must call a security API, CDR_PUB_API_INITIALIZATION, from every package that calls an Oracle Life Sciences Data Hub API and that you intend to run from outside Oracle Life Sciences Hub.

This API contains three functions:

• EnableApis sets the EnableAPIs flag to True.
• DisableApis sets the EnableAPIs flag to False.
• AreApisEnabled returns the flag setting.

The initialization of almost every API calls the AreApisEnabled function of the security API, CDR_PUB_API_INITIALIZATION, to check if the EnableAPIs flag is set to True in the calling program. If EnableAPIs set to False, the initialization fails.

To set the EnableApis flag to True, your user account must have Execute privileges on the CDR_PUB_API_INITIALIZATION API.

1. Begin the body with the following code to call the function to enable APIs:

   call cdr_pub_api_initialization.enableApis (arguments);

   The arguments are described in cdr_pub_api_initialization itself.

2. At the end of the body, disable APIs to force the security check on the schema the next time the program is run:

   cdr_pub_api_intialization.disableApis (arguments);

Package A: Package A is always run outside of Oracle Life Sciences Hub. Therefore you need to call EnableApis at the beginning of your package body and call DisableAPIs at the end.

Package B: You develop Package B outside of Oracle Life Sciences Hub, so you must call EnableApis at the beginning of the package body and call DisableAPIs at the end. However, you upload Package B to a Program inside an Oracle Life Sciences Hub Adapter Area and the adapter calls the functions and procedures and runs them inside Oracle Life Sciences Hub. Packages that call CDR_PUB_API_INITIALIZATION from within Oracle LSH fail.

Therefore, if you call public APIs from Package B, you must call EnableApis and DisableApis so that you can run the package outside Oracle Life Sciences Hub, but when you are ready to upload the code to Oracle Life Sciences Hub, you must comment out the calls.

You may well want to use public APIs in your custom functions and procedures. For example, if you allow users to upload Table Columns during Load Set definition, you can take advantage of the public API for creating Table Descriptors as part of the upload_table_columns function.