Resource Types and Entities

Introduction
Resource types and entities are Drupal Entities that are created, and managed, by the OSF Entities connector module. They are used to expose dataset contents indexed in a OSF Web Services instance into Drupal. The resource types and entities are available to other Drupal modules via the Entity API.

The OSF Entities module is called a "connector" module because it connects the OSF Web Services endpoints to the internal Drupal Entity API.

This page explains how the OSF Entities module can be used to search and browse for records in a OSF instance and how they can be created, updated, deleted and revisionned from Drupal.

This page is organized in three major sections:
 * How to configure the OSF Entities module
 * How to configure the Bundles and Fields to use in Drupal
 * How to manage resources using OSF Entities

Using OSF Entities and Resource Types
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
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,   and  , 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,   and   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  top menu item. 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  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  button. 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: 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  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.
 * 1) The dataset provenance of the records
 * 2) The type of the records

Then if you want to search only within a specific kind of records, then you can select that type, and click the 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  button to remove all the filters applied to that search. 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  button, you will be able to show/hide different columns. These settings will persist over time, for the user that you are logged with. 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: 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 columns comes into play. You do have two status possible in that column: If the status is, 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.
 * 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

If the status is, 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, then you will have an option to start exposing that class into Drupal.

The you have 4 different kind of operations possible: If the  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  link is clicked, then you will be redirected to a page that ask you if you really want to delete that record.

If the  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  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. If this option is checked, and if the  button is clicked, then it means that you will start seeing records that have a status of. By default, these  records are shown. However, you can hide them by using that option.

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  menu item. Then you have to click the  link. 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.

The next step is to click on one of these link to start creating a new record of these types. 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  section above.

There are minimally three (3) required fields in that form: 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.

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  tab. When you click the  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: In these forms, there are two different type of fields: You can distinguish the two kind of fields with three main cues. The fields that reference a record will: In the screenshot below, you have a  field that is used to tag a document with subject entities. This is one of these field that reference a record/entity. When you start typing in such a field, it will list all the possible values that you can reference with that field. Once the values that can be reference by that field will be displayed to you (in this case, the possible subject tags).
 * 1) Modify existing information
 * 2) Remove existing information
 * 3) Add new information to what already exists for that record
 * 1) The fields that reference another record/entity
 * 2) The fields that have a string as value
 * 1) Have the prefixed URI of the referenced record in parenthesis
 * 2) Will have a gray dot at the far right of the field
 * 3) When you will select the field with your mouse, it will start autocompleting what you are typing in the field

Then you have the fields that accept a string value, such as the  field below. You can put any text and any values in that field, and everything will be accepted. Finally, before saving a record, you will be asked if you want to moderate the modification you are doing. You have three options: If you choose one of the two options that create a revision, then you will see appearing a new  tab as shown below.
 * 1) Modify current resource, no revision, no moderation
 * 2) 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
 * 3) Create new revision, no moderation
 * 4) 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
 * 5) Create new revision and moderate
 * 6) 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.

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: By visualizing a revision, you see what the record will look like if it would be published.
 * 1) Visualize the revision by clicking on the   of the revision on the left side of a record line
 * 2) Publish a revision by clicking the   link in the   column
 * 3) Delete a revision by clicking the   link in the   column

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.

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

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: 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.
 * Click the delete link operation in the search user interface as shown above
 * Click the Delete tab when you are viewing a record

When you delete a record, internally, in an OSF instance, it is a  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 ( or hard  ).

Exporting Resources
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:
 * RDF+XML
 * RDF+N3
 * structXML
 * structJSON
 * irON JSON
 * irON commON (CSV)