Configuring OSF Entities and Resource Types

From OSF Wiki
Jump to: navigation, search

Configuring OSF Entities

Screencast Tutorial


Configuring OSF Entities is a process that you have to perform to map the classes and properties used in a remote OSF Web Services instance into internal Drupal bundles and fields. 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 Configuration menu item. Then, you have to click the Configure OSF for Drupal modules.

OSF for Drupal configurations

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

OSF Entities 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 Select Unused Classes and Select Unused Properties sections.

To access this configuration section, you have to click the Select Ontologies button:

Selecting ontologies

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 Save configuration button to save the configuration settings into Drupal.

OSF Entities select ontologies

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:

  1. The first step is to select all the classes that you want to expose into Drupal using bundles
  2. The second step is to select all the properties you want to expose into Drupal as field instances of the bundles you created in the previous step

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.

To start this mapping process, you have to click the Expose Entities button.

Osf entities configurations expose entities.png

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:

  1. Select Used Classes
  2. Select Unused Classes

It is important to understand the distinction between these two sections.

In the Select Used Classes 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.

Osf entities used classes.PNG

Then we have the Select Unused Classes 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.

If you cannot find the class that you are looking for, make sure that you selected the ontology where that class is defined, as explained in the Exposing ontologies to the mapping process section above.

Osf entities expose entities select unused classes.png

Once you are done, you have to click the Next, select properties 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.

Here is the list of all supported Field Type and Wiget by OSF Entities:

Field Type Field Type Machine Name Field Type Named Individual
Date date
Date (ISO format) datetime
Date (Unix timestamp) datestamp
Boolean list_boolean
Decimal number_decimal
File file
Image image
Float number_float
List (Float) list_float
List (Integer) list_integer
List (Text) list_text
Link link
Long text and summary text_with_summary
Long text text_textarea
Text text
Geolocation geolocation_latlng

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 Used Properties and Select Unused Properties section. The rational is the same. In the Used Properties 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 Select Unused Properties section.

Osf entities expose properties.PNG

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 Expose button.

Osf entities expose classes properties.PNG

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 Enable autocompletion fields for datatype properties values 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.

Struct entities configurations auto completion 2.png

Configuring OSF Resource Types

Once you clicked the Expose button in the previous classes and properties exposing process above, you then create a series of Drupal Bundles, Fields and Fields Instances. 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 Content Types 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 Resource Types bundles you created above, you have to click the Structure top menu item. This will show you the complete list of all the existing type of Drupal bundles. As you can see, there is a Resource Types item that you can click to see the complete list of Resource Types bundles that are currently existing on your Drupal portal.

Osf entities structure.png

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)
Osf entities structure resource types.png

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 Label). You can also add a description.

However, the most important option in this edition page is the Ignore synchronized resource 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 Ignored - in front of its label in the list of all the bundles (as you can notice in the screenshot above).

Osf entities structure resource types edit.png

Manage the Fields of a Resource Type Bundle

If you click the Manage fields 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.

Osf entities manage fields.PNG
Configuring Field Widgets

Once all the bundles and fields have been created in Drupal using the OSF Entities mapping process, you can continue the configuration process of these fields by specifying the field widgets you want to use for each of them, and then to configure each of these field widgets such that they behave the way you want them to behave.

The first thing to do is to click the field widget's name that appears in the WIDGET column of the list of fields in the bundle you are editing.

Osf entities manage fields widgets.PNG

Then you will be prompted with a list of field widgets that you can use for this field type. Select the one you want to use and save your configuration option. Then Drupal will prompt you with a series of additional configurations that you will be able to configure for that given field widget.

Here is the list of all the field widgets, by field type, that are supported by OSF Entities:

Field Type Field Widget Widget Example
Text Text Field
Img 5.PNG
OSF Entity Reference
Img 20.PNG
OSF Concept Reference (Tagging)
Img 19.PNG
Long text and summary Text area with a summary
Img 17.PNG
Long text Text area (multiple rows)
Img 19.PNG
List (text) Select list
Img 16.PNG
Check boxes/radio buttons
Img 15.PNG
List (integer) Select list
Img 16.PNG
Check boxes/radio buttons
Img 15.PNG
List (float) Select list
Img 16.PNG
Check boxes/radio buttons
Img 15.PNG
Link Link
Img 14.PNG
Integer Text field
Img 5.PNG
Float Text field
Img 5.PNG
Image Image
Img 13.PNG
File File
Img 10.PNG
Entity Reference Select list
Img 7.PNG
Check boxes/radio buttons
Img 6.PNG
Img 8.PNG
Autocomplete (Tags style)
Img 8.PNG
Decimal Text field
Img 5.PNG
Date (Unix timestamp) Text field
Img 3.PNG
Select list
Img 4.PNG
Pop-up calendar
Date (ISO format) Text field
Img 3.PNG
Select list
Img 4.PNG
Pop-up calendar
Date Text field
Img 3.PNG
Select list
Img 4.PNG
Pop-up calendar
Boolean Check boxes/radio buttons
Img 2.PNG
Single on/off checkbox
Img 1.PNG
Geolocation Latitude/Longitude
Img 11.PNG
Google Map
Img 12.PNG

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.

Osf entities manage fields display.PNG

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 Hidden section as shown below:

Osf entities manage fields display hidden.PNG

Once you are done modifying the display of the fields, you simply have to click the Save button.

Add a New Resource Type Bundle

At any time you can click the + Add new resource type link to create a new Resource Type. This will redirect you to this form that let you create a new Resource Type.

Osf entities manage create new resource type.PNG

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:

  • Name
    • 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
  • Ontology
    • The ontology where you want to create the new class that will be mapped to the new resource type
  • Description
    • The optional description of that resource type

Once you click the Save resource type button, two things will happen:

  1. A new class will be created in the selected ontology
  2. A new bundle will be created, and referring to that new class
The new class will be created under the Thing top concept of the selected ontology. If you want to re-organize the newly created class elsewhere in the ontologies structure, you should use the OSF Ontology module to position it elsewhere in your ontology.