Configuring OSF Entities and Resource Types

Configuring OSF Entities
Configuring OSF Entities is a process that you have to perform to map the  and   used in a remote OSF Web Services instance into internal Drupal   and. Every classes you want to expose in Drupal will be mapped as a bundle and every properties you want to expose in Drupal will be mapped as a field. Once this process of mapping classes and properties into bundles and fields is done, you will be able to use the OSF Entities module which means that you will be able to manage OSF records content from Drupal. To configure the OSF Entities module, you have to click on the top  menu item. Then, you have to click the.

Then click the  tab. Now you will see all the configuration options.

Exposing Ontologies to the Mapping Process
The first configuration step that needs to occur is to select the ontologies that are currently loaded into the OSF Web Services instances and that you want to use in the mapping process.

All the ontologies selected here will be exposed to the mapping process below. This means that all their classes and properties will be searchable in the  and   sections.

To access this configuration section, you have to click the  button: Once you clicked that button, you will be redirected to a new page that will list all the ontologies that are currently loaded in the OSF Web Services instances. The only thing you have to do in this section is to select all the ontologies you want to use in the mapping process by checking the checkboxes at their left.

Then you have to click the  button to save the configuration settings into Drupal.

Mapping Classes and Properties into Bundles and Fields
This is the crux of the OSF Entities configuration. This section explains how the classes and properties mapping process is working. This is a two step process: Once this configuration step is completed, you will be able to manipulate the OSF records natively into Drupal using its own internal API and various user interfaces.
 * 1) The first step is to select all the   that you want to expose into Drupal using bundles
 * 2) The second step is to select all the   you want to expose into Drupal as field instances of the bundles you created in the previous step

To start this mapping process, you have to click the  button. The first step of the process is to select all the classes that you want to expose to Drupal. A OSF Web Services instance is composed of number of datasets that defined hundred of thousands of records and that are defined using tens of classes and properties. However, not all these records and these classes necessarily need to be exposed into a Drupal portal. This is why the initial step is to only select the classes that we really want to expose to the Drupal portal.

All the classes that we will be selecting on this page will create a bundle in Drupal. What that means is that content maintainer will be able to create new records of these types. They will be able to modify existing records of these types, and they will be able to delete records of these types. This means that all the records of these selected classes will be manageable within the Drupal user interface.

This page as two major sections: It is important to understand the distinction between these two sections.
 * 1) Select Used Classes
 * 2) Select Unused Classes

In the  section, what we have there is a list of all the classes that are currently being used to describe record content into the OSF instance. This is a convenient way to say: check these classes, there are a good chance you want to map them since they are currently being used to describe records content into the OSF instance. By selecting classes in this section, you will create a new Drupal bundle for each of them.

Also note that some of the classes are pre-select and disabled (grayed). This means that these classes are always present in Drupal, and that they are core concepts that need to be mapped. Then we have the  section. This section is used to handle a specific usecase: you want to expose a class that is defined in a loaded ontology, however there is currently no record instances using that class in the OSF instance.

The common usecase for that section is that you want to create a new kind of record, in the OSF instance, using the Drupal user interface. Since no records of this type currently exists in the OSF instance, it means that it won't appear in the Select Used Classes section above. It is for that reason that you have to select the class in this section. Just like with the section above, a new bundle will be created from that class.

Once you are done, you have to click the Next,  button which will redirect you to the second page (step) of the mapping process.

Now that you selected the classes you want to map as bundles into Drupal, the next step is to select all the properties you want to map as fields into Drupal. When you create and modify records information in Drupal, you are doing this using conventional HTML forms. Each field of the form is a property and a value that you want to define to describe a specific instance record (a thing). What this property mapping does is to define all the fields that will be presented to the content maintainer in the create/edit forms generated by Drupal.

There is one important thing to know at this point: every field type that will be used for the fields that are created in this process are defined in the ontologies. If you want to know how you can influence the field type selection at this stage, I strongly suggest you to read the Configure Ontologies for Selecting Field Types page.

When you first get to that page, you will notice that there is a section for each and every classes you selected from the previous classes mapping step. What we are doing in this section is to select the properties to map for each of these classes you selected. What you have to do is to expend each of these section to make sure that you exposed all the properties you wanted to expose.

Just like with the classes mapping section, for each classes section, you have a  and   section. The rational is the same. In the  section, you get the list of all the properties that are currently used to describe a record of that class type in the OSF instance. Then, if you want to expose another property (that is not currently used), then you have to select it from the  section. Then, when you are done selecting all the properties for all the classes, the last thing you have to do is to click the Expose button. Depending on how many classes and properties you are mapping, it may take a few minutes to finish loading this process. You shouldn't close your browser's page, nor refresh the page while the page is loading after you click the  button. Once the next page loaded, you are done with the core of the OSF Entities configuration steps. You will now endup with a series of bundles and fields internally in Drupal. In the following sections we will see the impact of this exposition process, and what this enables you do to.

This process of exposing classes and properties into Drupal is not static in time. In the future, you will most than likely will have to start manipulating new kind of classes, or to start using new kind of properties for some of the bundles. What you will have to do is to do this process again to select more classes and properties to expose into Drupal.

Other Entities Settings
There is one other feature that can be configured into OSF Entities. This feature call  is used when you are creating new records, or when you are modifying existing ones. If you enable this configuration option, then it means that when you will create/edit a record using the Drupal user interface, all the fields (properties) that have strings has values will have an autocompletion behavior. What this autocompletion behavior will do is to list all the textual values currently defined in the OSF instance that are referenced by these properties by records of that same type.

This option is disabled by default but can be really powerful depending on the requirements.

Configuring OSF Resource Types
Once you clicked the  button in the previous classes and properties exposing process above, you then create a series of Drupal ,   and. These three things are what will enable you to generate the HTML forms that will be used to create new records and edit existing ones.

What will be discussed in this section is not different to what you do with the  bundles. These are just different kinds of bundles, used to manipulate records information in Drupal but directly into the OSF instance.

Create/Modify/Delete Resource Type Bundles and Fields
To see all the  bundles you created above, you have to click the   top menu item. This will show you the complete list of all the existing type of Drupal. As you can see, there is a  item that you can click to see the complete list of   that are currently existing on your Drupal portal. Once you clicked on that link, you will see a list of the existing bundles. There are multiple things you can do from that page:
 * You can edit the information about one of the bundle
 * You can manage the fields associated with one of the bundle
 * You can manage the display of the fields (how they get displayed in the generated HTML forms) of one of the bundle
 * You can re-organize the existing resource type (this redirect you to the first step of the exposition process as outlined above)
 * You can add a new resource type (this is a utility user interface that let you create a new class in an ontology, and then to create a bundle for it)

Edit a Resource Type Bundle
If you click on the Edit operation on the page that list all the existing bundles, you will get to that bundle edition page. What you can do here is to change the display name of that bundle (its ). You can also add a description.

However, the most important option in this edition page is the  type option. If this option is checked, it means that the exposed class won't be usable to the end user (for editing content of that type, to create new content of that type, etc). However, it will be usable internally by Drupal. If a bundle has this option checked, then you will see  in front of its label in the list of all the bundles (as you can notice in the screenshot above).

Manage the Fields of a Resource Type Bundle
If you click the  link from the page that lists all the bundles, then you will get to this section that enable you to edit the fields currently defined for the bundle. What you can do here is to change the field, remove it, change its label, etc. by clicking the different operations.

Manage the Display of Fields for a Resource Type Bundle
If you click the Manage display link from the page that lists all the bundles, then you will get to this section that let you re-order and modify the display of these fields. As you will see in the sections below, all the fields of a bundle will be displayed as an HTML form that the content maintainer will use to create and edit records data in the OSF instance. What you can do is to re-order the fields in that list such that you get the more important fields at the top of the form, etc. What you can additionally do is to hide some of the fields. What that means that is these fields will still be taken into account, but they won't be displayed in the forms that will be generated by Drupal. To be able to hide such a field, you have to drag-and-drop it into the  section as shown below: Once you are done modifying the display of the fields, you simply have to click the  button.

Add a New Resource Type Bundle
At any time you can click the  link to create a new. This will redirect you to this form that let you create a new Resource Type. As you know, all the resource type bundles are referring to an ontology class existing in the loaded ontologies in a OSF instance. What this feature does is to bypass the classes mapping workflow as described above to directly create a new class in a selected ontology, and then to create a new bundle for it. What you have to specify is: Once you click the button, two things will happen:
 * The name of the new Resource Type to create. This name will be used to create the URI of the class in the selected ontology
 * The ontology where you want to create the new class that will be mapped to the new resource type
 * The optional description of that resource type
 * The ontology where you want to create the new class that will be mapped to the new resource type
 * The optional description of that resource type
 * The optional description of that resource type
 * 1) A new class will be created in the selected ontology
 * 2) A new bundle will be created, and referring to that new class