Using OSF Entities and Resource Types

From OSF Wiki
Jump to: navigation, search

This section will show you all the features that are enabled on the OSF Entities is configured in a Drupal instance.

Browsing and Searching Resources

Screencast Tutorial

0.jpg

One of the core feature that OSF Entities provide, is a tool that the content authors can use to search, browse and filter all the content they have access to from a OSF instance. What that means is that if a particular user only has access to the datasets X, Y and Z, then he will only see the results from these datasets when he will be using this search, browse and filter tool. Another user that has access to the datasets A, B and C will only see the results from these datasets as well. This means that this same user interface can be used to navigate information from the data sources a user has access to.

To access this section, you have to click the Resource top menu item.

Osf entities resource tab.png

Once you clicked that menu item, you will be redirected to a page that will let you search, browse and filter the information you have access to. The first operation to perform can be a simple search query for the keyword 'iowa'. Once you clicked the Search button, you will get a list of results that match this keyword.

If you want to remove the search keyword, and if you want to re-perform the search without that keyword, you you simply have to click the Remove button.

Osf entities resources search.PNG

Once you started to search for specific records, you can additionally apply different filtering criterias to the search query. There are currently two filtering criterias that you can use to filter your data:

  1. The dataset provenance of the records
  2. The type of the records

If you want to search exclusively within the content of a dataset, then what you will have to do is to select that dataset and click the Filter button. Once you clicked that button, a search will be re-issued by the system, and you will be presented all the records, from that dataset, that match the search keywords.

Then if you want to search only within a specific kind of records, then you can select that type, and click the Refine button. At that point, you will be performing a search that match the search keywords, for the records indexed in that dataset and that use that type.

At any time you can click the Reset button to remove all the filters applied to that search.

Osf entities resources search filter.PNG

Another option you have is to select the columns you want to display on that page. Not all columns are necessary for everybody. By checking the columns and by clicking the Reorganize button, you will be able to show/hide different columns. These settings will persist over time, for the user that you are logged with.

Osf entities resources search columns.PNG

Once you did perform a search, you will get a series of matching records from the OSF instance. Depending on the columns you have selected, you will see:

  1. The preferred label of the record
  2. The URI of the record (hidden by default)
  3. The type of the record
  4. The dataset provenance of the record
  5. The status of the record
  6. Different operations you can perform on the record

When you use this searching tool, you are searching all the records you have access to in the OSF instance. However, it is not necessarily all the record types that have been exposed as bundle in Drupal. This is where the STATUS columns comes into play. You do have two status possible in that column:

  1. Exposed
  2. Available

If the status is Exposed, then it means that the record that is returned to you is currently exposed in Drupal. That means that there exists a bundle for that type of record.

If the status is Available, then it means that the record is accessible to you, but that there is no bundle that expose that type of record to Drupal. This means that this class didn't get exposed to Drupal and so that no bundle exists for that kind of record. If a record is marked as Available, then you will have an option to start exposing that class into Drupal.

The you have 4 different kind of operations possible:

  1. Edit
  2. Delete
  3. Configure dataset for editing
  4. Expose

If the edit link is clicked, then you will be redirected to a page where you will be able to edit all the information related to that record.

If the delete link is clicked, then you will be redirected to a page that ask you if you really want to delete that record.

If the configure dataset for editing link is displayed for a record, that means that this record is indexed in a dataset that you have access to, but that is not currently configured in the OSF for Drupal module. What that means is that this record is no available to any other OSF for Drupal tool since it is not (yet) configured in OSF Configure. Once it get configured in OSF Configure, the available options will change accordingly.

If the expose link is displayed for a record, that means that the record is available, but there is no bundle for its type. If you click on that link, you will be redirected to expose that type class as a bundle in Drupal.

Finally, you have a final filtering option that is available to you check is called Show available records that are not currently exposed in the portal. If this option is checked, and if the Show available button is clicked, then it means that you will start seeing records that have a status of available. By default, these available records are shown. However, you can hide them by using that option.

Osf entities resources search available.PNG

Creating New Resources

One of the core reason why we want the OSF Entities module enabled and configured is to be able to create new records and to index them directly into the OSF instance. That means that the new record would become available to other portals that would use the same OSF instance.

To create a new record, you have to click the top Resource menu item. Then you have to click the + Add resource link.

Osf entities add record.png

Once you clicked that link, you will be redirected to a page that will display all the type of Resource Type records that you can create.

If you edited the created bundles, and if you clicked the option Ignore synchronized resource type then you won't see these bundles appearing in that list.


The next step is to click on one of these link to start creating a new record of these types.

Osf new resource.PNG

Once you clicked on one of these links, then you will be redirected to a page where you will see an HTML form that you will be able to use to populate information about that new record you are about to create. This form is generated by Drupal depending on the way to configured the bundle and its fields in the Configuring Resource Type Bundles and Fields section above.

There are minimally three (3) required fields in that form:

  1. Unique identifier
  2. Dataset
  3. Preferred label

The first thing to determine is what is the unique identifier of the new record you are creating. This unique identifier is a string that as alpha numeric characters, underscores "_", dot "." or dash "-" characters. The unique identifier can be anything. However it is normally related to the preferred label you will choose to define. An example of unique identifier could be "iowa_public_school_a".

The the second thing you have to determine is where the record should be indexed, in which dataset. The user interface will present you a drop-down list of all the datasets where you can create new records.

Finally you will have to write the preferred label of that record.

Once you defined your unique identifier, and once you selected your dataset, you will be defining the complete unique identifier (URI) of the record you are about to create.

Let's say that you defined the unique identifier to be iowa_public_school_a. Then you choose the dataset "Iowa Public Schools". This dataset has the URI http://localhost/datasets/iowa_public_schools/.

What the system will do is to create a final unique identifier by concatenating these two values. This means that the real URI of the record you creating will be:

http://localhost/datasets/iowa_public_schools/iowa_public_school_a


Osf creating new resource.PNG

Finally what you can do is to add values for all the other fields displayed in that HTML form.

Modifying and Revising Resources

Another of the core reason why we want the OSF Entities module enabled and configured is to be able to modify and revision existing records directly into the OSF instance. That means that the changes to a record will become available to other portals that would use the same OSF instance.

If you click on one of the record displayed by the search tool discussed above, you will get to that page below. What this page does is to show you a (generic) view of that record which list all the properties and values that define that record. As you can notice, there are a few tabs at the top of that page. The one that currently interest us is the Edit tab.

Osf entity view.PNG

When you click the Edit tab, you get redirected to a page similar to the one that we saw when we were creating a new record. The main difference is that the fields are pre-populated with the current values that describe that record. The purpose of this user interface is that it let you:

  1. Modify existing information
  2. Remove existing information
  3. Add new information to what already exists for that record
Osf entity edit.PNG

In these forms, there are two different type of fields:

  1. The fields that reference another record/entity
  2. The fields that have a string as value

The fields that reference other records/entities are using the OSF Entity Reference field widget. You should refer to the Configuring and Using the OSF Entity Reference Field Widget page to know how to configure and use that widget. You will only be able to reference entities that currently exists into the OSF instance. The widget will let you search for the entities you want to reference. Depending how the widget is configured, you will be able to select one or multiple entities. All the selected entities will appear in blue boxes like this:

Img 20.PNG

Then the fields that have a string has value (so, all the fields that doesn't reference to another entity) can use a long list of field widgets. Each of these field widgets are different user interfaces that are used to help the user to specify the right value for a given property/field. Here is the list of all these field widget currently supported by OSF Entities, and a screenshot of each of them:


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
Autocomplete
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

Finally, before saving a record, you will be asked if you want to moderate the modification you are doing. You have three options:

  1. Modify current resource, no revision, no moderation
    1. If this option is used, then the modifications you did to this record will be directly modified in the OSF instance without creating a revision with the changes. With this option, rollback of the changes is not possible
  2. Create new revision, no moderation
    1. If this option is used, then the modifications you did to this record will be directly modified in the OSF instance, but a new revision record will be create with these changes. With this option, roolback o the changes is possible
  3. Create new revision and moderate
    1. If this option is used, then the modifications you did to this record will not be directly modified in the OSF instance. A new revision will be created with the changes, but the modifications of the record won't be published. These changes will need to be moderated, and then they will eventually be published to the dataset.
Osf entities entity edit revision.png

If you choose one of the two options that create a revision, then you will see appearing a new Revisions tab as shown below.

If you click on that tab, you will be presented a list of revisions that exists for that record. The currently published revision will appear with a yellow background. For each revision, you have three operations:

  1. Visualize the revision by clicking on the date of the revision on the left side of a record line
  2. Publish a revision by clicking the revert link in the Operations column
  3. Delete a revision by clicking the delete link in the Operations column

By visualizing a revision, you see what the record will look like if it would be published.

By publishing a revision, you are in fact re-creating a new revision record, but using this previous status. This means that the published record will become a copy of the revision where you clicked revert.

By deleting a revision, you are simply deleting the revision in the system. This means that you won't be able to rollback the changes you made with that revision.

Osf entities entity edit revision view.png

Another thing you can do with this revisions section, is to compare two revisions. To compare two revisions, you have to click the compare link of one of the revision record. Once you did this, the values of the Compare column will change. Then what you have to do is to click the with link such that you compare the revision you previously selected with that other revision.

Osf entities entity edit revision compare.png

Once you selected the two revisions records that you want to compare, you will be presented a user interface that show you all the modifications that occurred between the two revisions. What you will see in this user interface is:

  • The new properties/values that may have been added on one side or the other
  • All the text, within the values, that may have change (added or removed), one one side or the other
Osf entities entity edit revision compare view.png

Deleting Resources

Another thing you can do with OSF Entities is to delete a record in the OSF instance using the Drupal user interface. What you have to do to delete a record is to:

  • Click the delete link operation in the search user interface as shown above
  • Click the Delete tab when you are viewing a record

Once you did one of these two actions, you will be presented a user interface that ask you if you are really sure to want to remove that record.

When you delete a record, internally, in an OSF instance, it is a soft delete that is performed. What this means is that the record is actually unpublished. However, all the revisions of the record are still existing which means that it could be re-published in the future. However, there is currently no facility in the OSF Entities to detect these records for re-publishing them in the future, this would need to be done by hands directly on the OSF instance. Also, in the future, an option could be presented to use user to know which kind of delete he would like to perform (soft or hard delete).

Osf entities entity delete.png

Exporting Resources

Screencast Tutorial

0.jpg

All and every Resources Entities can be exported. If the permissions are properly configured, an Export tab appears on the individual records pages. By clicking on that tab, you will be redirected to a page that list a series of serialization format that you can use to export the content of that resource page. The supported formats are:

Osf entities entity export.png