Saving Local Content in OSF

From OSF Wiki
Jump to: navigation, search


Screencast Tutorial


In Drupal, Content Type entities are by default saved into the default field storage system, which is MySQL. This is what we call "local content". This type of content is "local" to Drupal.

What this page will show, is that it is possible to save the values of some of the [local] Content Types directly into OSF instead of Drupal. This magic is performed by the OSF FieldStorage module which creates a new FieldStorageAPI for Drupal. What this module does is to create a new kind of storage (OSF) to save the values of some of the fields (the ones that have been created using that new storage system).

What that means is that for the same Content Type entity, you may have 2 of its fields that are saved in Drupal (MySQL) and 4 of its other fields saved into OSF. Or you could have all of them in MySQL, or all of them in OSF. Everything depends on how you configure the Content Type entities.

You can read more about the internal mechanism of the OSF Field Storage module by reading the Single Authoring Environment: the OSF FieldStorage Connector page.

Configuring OSF FieldStorage

Before configuring any Content Type entity using the new osf_fieldstorage system we have to configure a few settings in the OSF FieldStorage module. To access these settings, 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 Local Storage tab. Now you will see all the configuration options.

Field storage config.PNG
  • Content Type Default Field Storage System
    • Change the default storage system of the Content Types to use the osf_fieldstorage system by default instead. By selecting this option, all the future field that will be created for the Content Types will be using a OSF instance as field data storage system. This means that the field_sql_storage storage system won't be available anymore when you will be managing your fields.
  • Field RDF Mapping
    • By default, only the field that uses the osf_fieldstorage field storage system will appear in the list of fields to be mapped in RDF under the RDF MAPPING tab. This means that only the mapped fields will be saved into the OSF instance. By enabling this option, you will see all the fields, whatever the field storage system they are using to be mapped in RDF. All the mapped fields will be saved into the OSF. This option could be used when synchronizing existing content on a Drupal instance that is no in OSF but that needs to be there.
  • Local Storage Content Dataset
    • Select the dataset you want to use to save all the local content you are creating from this Drupal instance. The local content is all the Content Types such as the Nodes, Articles, Pages, etc.
Note: It is essential that you select a dataset where to save the local content (the Content Type entities). If none are selected, no information will be saved for the osf_fieldstorage fields.

Configuring Drupal Content Type

Now that the OSF FieldStorage is properly configured, the next step is to configure existing, or new, Content Type entities to use the new osf_fieldstorage system.

To access the Content Types, you have to click the Structure top menu, and then click on the Content types link.

Field storage structure.PNG

What you get is the list of Content Types currently defined in your Drupal portal. From there, you can manage the ones that are created, or create new ones.

The option that particularly interest us is to manage the fields of a Content Type to choose the fields that will be used to describe one of these entity, and more particularly, which FieldStorage system it should be using.

Click the manage fields link to start managing the fields of a Content Type.

Field storage content types.PNG

In the manage fields section of a Content Type, you can see all the fields that are defined for a given Content Type. You can add, remove or edit fields as required. Each field is associated with a field widget. That field widget is a tool that will help the user to find or describe the right value for a field.

Field storage manage fields.PNG

The user interface of the original Content Type manage fields section only slightly changed compared to what you may be familiar with. The changes are:

  • A new Storage Type columns where you can see the FieldStorage type used by the field
  • A new Add new field (using osf_fieldstorage) used to creae a new field that uses the osf_fieldstorage type

With this new user interface in place, you can create a new field that uses the osf_fieldstorage type, or the default field_sql_storage type.

If you want to change the storage type of an existing field, you have no other choices than deleting it and re-creating it with the new type.

Note: If you delete a field_sql_storage field, you will loose all the information associated to it. You should synchronize its information in OSF before deleting it.

Field storage manage fields storage type.PNG

If you want to create a new field that uses the osf_fieldstorage field, then you have to define a name for it, then to select a field type and a field widget. None of this is different than what you were used to with the normal Content Type user interface.

The list of supported Field Type and Wiget is:

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

When you will click the Save button, you will be redirected to more configuration pages depending which field type and field widget you selected.

Field storage manage adding osf field.PNG

When the new field is created, you will see it appearing in the list of fields with the storage type you selected at the beginning.

Field storage manage field added.PNG

The next essential step is to map the newly created field to a RDF property. It is this mapping that will tell the system how to save the field's information into OSF in RDF. To manage this mapping you should click on the RDF MAPPINGS tab. This section will show you two things:

  1. The type of the content type
  2. All the fields of the content type

Then for each of these things, you will be able to define how it should be mapped in RDF.

If you do not select a type for the content type, then the default internal Drupal mapping will be used, which is sioc:Item. Then you have to map all the fields to different properties that are currently defined in loaded ontologies.

Note: If you do not map a field to a RDF property after you created it, nothing will be saved in OSF. So it is really important to map the new field to a RDF property.

Once you are done mapping the fields, you can click the Save mappings button to save the mapping.

Field storage manage new field rdf mapping.PNG

Creating/Editing Content Type Record

Once you are done with all these steps, you can to do edit an existing Content Type record, or to create a new one and save it. Depending on the field type you choose, the information will be saved in OSF or in MySQL (or any other possible FieldStorage type).

Field storage manage edit content type record.PNG

Using OSF FieldStorage to Synchronize Existing Drupal Local Content to OSF

Sometimes there are situation where you would like to have all your local content type pages be saved into a OSF instance. This section gives you all the steps required to take an existing Drupal portal's content and to synchronize/export it into a OSF instance. This process is particularly helpful if you already have an existing site with dozens of content types and thousands of pages that you want to start managing on OSF (along with other content assets). The procedure explained here can be helpful for other usecases. For example, we already used to to migrate a OSF version 1.1 environment into a OSF 3.0 one. All the local content needed to be part of the new OSF 3.0 instance, and this method has been utilized.

Normally there are at least two reasons why we want to synchronize Drupal local content types into OSF:

  1. Because you want to stop using the FieldStorage, and want to manage all this content directly into OSF using the Entity API
  2. Because you want your local content be searchable with all the other OSF dataset assests via the OSF SearchAPI module

In any case, it is the same procedure that should be utilized.

Configuring the Local Content Synchronization Process

The first thing you have to do before performing the synchronization process is to map all the fields of the content type you want to synchronize in OSF to the classes and properties that you want to use for saving the information in OSF. To perform this mapping, you have to click on the RDF MAPPINGS tab. Then you have to make sure that all the types and properties you want to save in OSF are properly mapped:

Fieldstorage sync 2.PNG

Take note: if you didn't enable the All fields can be mapped into RDF and saved into OSF option in the OSF FieldStorage options, then you will only see the fields that uses the osf_fieldstorage field storage type. If you want to map osf_fieldstorage and field_sql_storage types, then you have to select that option, save it, and then go back to the RDF MAPPINGS tab to do the mappping of these non-osf_fieldstorage fields.

You also have to specify the dataset that will contain all the synchronized local data content. All the synchronized local content will be saved into that single dataset.

Fieldstorage sync 6.PNG

Once the mapping is complete, you have to make sure that you have at least one field that uses the osf_fieldstorage field storage type. It is necessary to have at least one to see the SYNCHRONIZE tab appearing. If you don't need any, then what you should do is to create a dummy field that uses the osf_fieldstorage type and hide it to the users afterward.

Fieldstorage sync 1.PNG

Once everything is properly configured, and that you can see and click the SYNCHRONIZE tab, then you are ready to start the synchronization process. It is as simple as clicking the Synchronize Content Type button.

Fieldstorage sync 3.PNG

Once you clicked the button, you will get into the synchronization process. All the local content will be synchronized into OSF using that process.

Fieldstorage sync 4.PNG

Then when the process ends, you will get a report that everything did go fine, with the number of pages processed.

Fieldstorage sync 5.PNG

At that point, all the data is saved into the local content dataset.